playbooks

home / skills / derklinke / codex-config / ios-swift-concurrency-expert

ios-swift-concurrency-expert skill

/skills/ios-swift-concurrency-expert

This skill reviews and fixes Swift Concurrency issues in Swift 6.2+ codebases, applying actor isolation, Sendable safety, and modern patterns with minimal

npx playbooks add skill derklinke/codex-config --skill ios-swift-concurrency-expert

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.7 KB
---
name: swift-concurrency-expert
description: Swift Concurrency review and remediation for Swift 6.2+. Use when asked to review Swift Concurrency usage, improve concurrency compliance, or fix Swift concurrency compiler errors in a feature or file.
---

# Swift Concurrency Expert

## Overview

Review and fix Swift Concurrency issues in Swift 6.2+ codebases by applying actor isolation, Sendable safety, and modern concurrency patterns with minimal behavior changes.

## Workflow

### 1. Triage the issue

- Capture the exact compiler diagnostics and the offending symbol(s).
- Identify the current actor context (`@MainActor`, `actor`, `nonisolated`) and whether a default actor isolation mode is enabled.
- Confirm whether the code is UI-bound or intended to run off the main actor.

### 2. Apply the smallest safe fix

Prefer edits that preserve existing behavior while satisfying data-race safety.

Common fixes:

- **UI-bound types**: annotate the type or relevant members with `@MainActor`.
- **Protocol conformance on main actor types**: make the conformance isolated (e.g., `extension Foo: @MainActor SomeProtocol`).
- **Global/static state**: protect with `@MainActor` or move into an actor.
- **Background work**: move expensive work into a `@concurrent` async function on a `nonisolated` type or use an `actor` to guard mutable state.
- **Sendable errors**: prefer immutable/value types; add `Sendable` conformance only when correct; avoid `@unchecked Sendable` unless you can prove thread safety.

## Reference material

- See `references/swift-6-2-concurrency.md` for Swift 6.2 changes, patterns, and examples.
- See `references/swiftui-concurrency-tour-wwdc.md` for SwiftUI-specific concurrency guidance.

Overview

This skill reviews and remediates Swift Concurrency usage for Swift 6.2+ codebases. It focuses on actor isolation, Sendable safety, and modern async/await patterns while preserving existing behavior. Use it to resolve compiler errors, remove data-race risks, and make concurrency intentions explicit.

How this skill works

I triage compiler diagnostics, identify actor contexts (for example @MainActor, actor, nonisolated), and determine whether code is UI-bound or background work. I apply the smallest safe change to satisfy the compiler and concurrency safety: adding actor annotations, moving state into actors, or converting work to async tasks. I prefer explicit, minimal edits that maintain semantics and avoid unsafe shortcuts unless proven safe.

When to use it

  • When Swift 6.2+ compiler reports actor isolation or Sendable errors
  • When migrating legacy code to async/await or modern concurrency APIs
  • When UI code needs correct @MainActor annotations to avoid race conditions
  • When global or static mutable state triggers data-race concerns
  • When adopting structured concurrency and you need help choosing actors vs. nonisolated async functions

Best practices

  • Capture exact compiler diagnostics before changing code to ensure focused fixes
  • Prefer smallest behavior-preserving changes first (annotations, isolated extensions)
  • Annotate UI-bound types with @MainActor rather than scattering main-actor calls
  • Protect mutable shared state by moving it into an actor instead of ad-hoc locking
  • Favor immutable/value types for Sendable conformance; avoid @unchecked Sendable unless you can justify thread safety
  • Convert heavy background work into nonisolated async functions or actors with @concurrent methods where appropriate

Example use cases

  • Fix a compiler error where a UIViewController extension needs @MainActor conformance for a protocol
  • Convert a global mutable cache into an actor to eliminate data races
  • Resolve Sendable warnings by replacing captured mutable references with value types or explicit Sendable conformance
  • Refactor expensive synchronous work into Task/async functions running off the main actor
  • Annotate static APIs and isolated extensions to make protocol conformances compile without changing call sites

FAQ

Will you always add @unchecked Sendable to silence warnings?

No. I avoid @unchecked Sendable except when you can prove no concurrent mutation occurs. Prefer immutable types or correct Sendable conformance.

How do you decide between an actor and @MainActor?

Use @MainActor for UI-bound types that must run on the main thread. Use an actor to protect mutable shared state accessed from multiple threads or for background concurrency coordination.