swift-concurrency

Files (28)

• SKILL.md
• actors.md · references/
• approachable-concurrency.md · references/
• async-algorithms.md · references/
• async-await-basics.md · references/
• async-sequences.md · references/
• async-streams.md · references/
• bridging.md · references/
• bug-patterns.md · references/
• cancellation.md · references/
• core-data.md · references/
• diagnostics.md · references/
• glossary.md · references/
• hotspots.md · references/
• interop.md · references/
• linting.md · references/
• memory-management.md · references/
• migration.md · references/
• new-features.md · references/
• performance.md · references/
• sendable.md · references/
• structured.md · references/
• swift-6-2-concurrency.md · references/
• swiftui-concurrency-tour-wwdc.md · references/
• tasks.md · references/
• testing.md · references/
• threading.md · references/
• unstructured.md · references/

SKILL.md (first lines)

Review, write, and improve Swift Concurrency code for correctness, modern API usage, data-race safety, and adherence to project conventions. Report only genuine problems — do not nitpick or invent issues.


## First 60 seconds (triage template)

Before making recommendations, capture the minimum context you need:

- **Swift language mode** (Swift 5.x vs Swift 6) and SwiftPM tools version.
- **Default actor isolation** — is the module default `@MainActor` or `nonisolated`? (Swift 6.2 "approachable concurrency".)
- **Strict concurrency level** — minimal / targeted / complete.
- **Upcoming features** enabled, especially `NonisolatedNonsendingByDefault` and `InferIsolatedConformances`.
- **Current actor context** of the offending symbol — `@MainActor`, custom actor, instance isolation, or nonisolated.
- **Is the code UI-bound** or intended to run off the main actor?

If any of these are unknown, ask the developer to confirm before giving migration-sensitive guidance.


## Project Settings Intake

Before diving in, inspect the build settings:

- **SwiftPM**: check `Package.swift` for
  - `// swift-tools-version: ...` (a hint, not authoritative for language mode — prefer `swiftLanguageModes`/`swiftLanguageVersions` or an explicit `-swift-version`)
  - `.defaultIsolation(MainActor.self)`
  - `.enableUpcomingFeature("NonisolatedNonsendingByDefault")`
  - `.enableExperimentalFeature("StrictConcurrency=targeted")` (or similar)
- **Xcode projects**: search `project.pbxproj` for
  - `SWIFT_DEFAULT_ACTOR_ISOLATION`
  - `SWIFT_STRICT_CONCURRENCY`
  - `SWIFT_UPCOMING_FEATURE_` (and/or `SWIFT_ENABLE_EXPERIMENTAL_FEATURES`)

```bash
rg "SWIFT_DEFAULT_ACTOR_ISOLATION|SWIFT_STRICT_CONCURRENCY|SWIFT_UPCOMING_FEATURE_" -n
```


## Review process

1. Scan for known-dangerous patterns using [references/hotspots.md](references/hotspots.md) to prioritize what to inspect.
2. Check Swift 6.2 concurrency behavior using [references/new-features.md](references/new-features.md), [references/swift-6-2-concurrency.md](references/swift-6-2-concurrency.md), and (if opted in) [references/approachable-concurrency.md](references/approachable-concurrency.md).
3. Validate actor usage, reentrancy, and isolation correctness using [references/actors.md](references/actors.md).
4. Validate Sendable conformance using [references/sendable.md](references/sendable.md).
5. Check threading, isolation domains, and nonisolated patterns using [references/threading.md](references/threading.md).
6. Ensure structured concurrency is preferred over unstructured where appropriate using [references/structured.md](references/structured.md) and [references/tasks.md](references/tasks.md).
7. Check unstructured task usage for correctness using [references/unstructured.md](references/unstructured.md).
8. Verify cancellation is handled correctly using [references/cancellation.md](references/cancellation.md).
9. Validate async stream, continuation, and AsyncSequence usage using [references/async-streams.md](references/async-streams.md) and [references/async-sequences.md](references/async-sequences.md).
10. For complex stream composition, check [references/async-algorithms.md](references/async-algorithms.md).
11. Check `async`/`await` basics and common `async let` / `withTaskGroup` patterns using [references/async-await-basics.md](references/async-await-basics.md).
12. Check memory safety (retain cycles in tasks) using [references/memory-management.md](references/memory-management.md).
13. Check bridging code between sync and async worlds using [references/bridging.md](references/bridging.md).
14. Review any legacy concurrency migrations using [references/interop.md](references/interop.md) and [references/migration.md](references/migration.md).
15. Review Core Data–specific concurrency using [references/core-data.md](references/core-data.md).
16. Cross-check against common failure modes using [references/bug-patterns.md](references/bug-patterns.md).
17. If the project has strict-concurrency errors or SwiftLint warnings, map diagnostics to fixes using [references/diagnostics.md](references/diagnostics.md) and [references/linting.md](references/linting.md).
18. For performance tuning, see [references/performance.md](references/performance.md).
19. For SwiftUI-specific concurrency, see [references/swiftui-concurrency-tour-wwdc.md](references/swiftui-concurrency-tour-wwdc.md).
20. If reviewing tests, check async test patterns using [references/testing.md](references/testing.md).
21. For terminology, see [references/glossary.md](references/glossary.md).

If doing a partial review, load only the relevant reference files.


## Core Instructions

- Target Swift 6.2 or later with strict concurrency checking.
- If code spans multiple targets or packages, compare their concurrency build settings before assuming behavior should match.
- Prefer structured concurrency (task groups) over unstructured (`Task {}`).
- Prefer Swift concurrency over Grand Central Dispatch for new code. GCD is still acceptable in low-level code, framework interop, or performance-critical synchronous work where queues and locks are the right tool — don't flag these as errors.
- If an API offers both `async`/`await` and closure-based variants, always prefer `async`/`await`.
- Do not introduce third-party concurrency frameworks without asking first.
- Do not suggest `@unchecked Sendable` to fix compiler errors. It silences the diagnostic without fixing the underlying race. Prefer actors, value types, or `sending` parameters instead. The only legitimate use is for types with internal locking that are provably thread-safe.
- Do not recommend `@MainActor` as a blanket fix. Justify why main-actor isolation is correct for the code.
- Use `Task.detached` only with a clear, documented reason.
- If recommending `@preconcurrency`, `@unchecked Sendable`, or `nonisolated(unsafe)`, require a documented safety invariant and a follow-up ticket to remove or migrate it.
- For migration work, optimize for minimal blast radius — small, reviewable changes plus verification steps.


## Triage-First Playbook

Common errors → next best move:

- **SwiftLint concurrency-related warnings** → use [references/linting.md](references/linting.md) for rule intent and preferred fixes. Never "fix" `async_without_await` by adding a dummy `await`; remove the unused `async` or suppress narrowly.
- **"Sending value of non-Sendable type ... risks causing data races"** → identify where the value crosses an isolation boundary, then check [references/sendable.md](references/sendable.md) and [references/threading.md](references/threading.md) (especially Swift 6.2 behavior changes).
- **"Main actor-isolated ... cannot be used from a nonisolated context"** → decide if it truly belongs on `@MainActor`; then use [references/actors.md](references/actors.md) (global actors, `nonisolated`, isolated parameters) and [references/threading.md](references/threading.md).
- **"Class property 'current' is unavailable from asynchronous contexts"** (Thread APIs) → use [references/threading.md](references/threading.md) to stop thread-centric debugging and rely on isolation + Instruments.
- **XCTest async errors like "wait(...) is unavailable from asynchronous contexts"** → use [references/testing.md](references/testing.md) (`await fulfillment(of:)` and Swift Testing patterns).
- **Core Data concurrency warnings/errors** → use [references/core-data.md](references/core-data.md) (DAO / `NSManagedObjectID`, default isolation conflicts).
- **"Actor cache duplicates downloads / force-unwrap crash"** → classic reentrancy bug; see [references/actors.md](references/actors.md).


## When to use each concurrency tool

**`async`/`await`** — making existing synchronous code asynchronous:

```swift
func fetchUser() async throws -> User {
    try await networkClient.get("/user")
}
```

**`async let`** — fixed number of parallel operations known at compile time:

```swift
async let user = fetchUser()
async let posts = fetchPosts()
let profile = try await (user, posts)
```

**`Task`** — fire-and-forget work, bridging sync to async contexts:

```swift
Task {
    await updateUI()
}
```

Choose the task's entry isolation from its synchronous prefix (everything before the first `await`): keep the inherited `@MainActor` start only when that prefix needs main-actor access, otherwise use `Task { @concurrent in ... }` and hop back via `await MainActor.run { ... }` for UI mutation. A trivial non-main line (e.g. `print`) does not justify `@concurrent` when main-actor work already exists in the prefix. This matters most in `defaultIsolation(MainActor.self)` codebases — see [references/tasks.md](references/tasks.md).

From ducko-im/ducko, MIT.

More from ducko-im/ducko