Swift

User preferences and memory live in ~/Clawic/data/swift/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/swift/ or ~/clawic/swift/), move it to ~/Clawic/data/swift/.

When To Use

• Writing, reviewing, or refactoring Swift: models, protocols, generics, async code, SwiftUI views, packages
• Diagnosing a crash from its message, or a hang with no message: nil unwrap, arithmetic overflow, unowned dangling, exclusivity violation, continuation never resumed
• Fixing Swift 6 data-race errors, Sendable conformance failures, and actor-isolation diagnostics during a language-mode migration
• Chasing memory: retain cycles, objects that never deinit, growth Instruments blames on nothing
• Making builds and binaries faster: type-check blowups, generic bloat, ARC traffic, existential boxing
• Shipping Swift off Apple platforms: Linux and server builds, static linking, Foundation gaps, C interop
• Not for Xcode project settings, signing, or provisioning (→ xcode), and not for App Store review, app lifecycle, or platform frameworks (→ ios)

Quick Reference

Core Rules

1. ! is a deliberate crash, not a shortcut. Recoverable nil → guard let x else { return }. Nil that means the program is already broken → guard let x else { fatalError("config missing: \(key)") }; the crash log then names the invariant instead of "Unexpectedly found nil while unwrapping an Optional value", which names nothing. Only IBOutlets and two-phase init justify an implicitly unwrapped T!.
2. weak when the target can die first; unowned only when lifetimes are provably nested. Test: can the referenced object deallocate while this reference exists? Yes → weak (becomes nil, no crash). Provably no, because it owns me → unowned (one less check, but a dangling read is an immediate crash rather than a nil). Escaping closures that touch self: [weak self] in guard let self else { return }. Non-escaping closures (map, forEach, withLock) never need a capture list — they cannot outlive the call.
3. Reference type only for identity or lifecycle. Default struct. Reach for class/actor when the thing has identity (two copies with equal fields are still different things), needs deinit, or is genuinely shared and mutated in place. Copy cost is not the tiebreaker: standard-library collections are copy-on-write, so a copy is a retain until someone writes (→ types.md).
4. Never block a thread in the cooperative pool. Swift concurrency runs one thread per active core, so on an 8-core machine 8 concurrent DispatchSemaphore.wait() calls inside async functions deadlock the whole process — no error, no timeout. Bridge blocking work out to a dedicated DispatchQueue or thread, and await everything else.
5. Every withCheckedContinuation resumes exactly once on every path. Twice = runtime trap ("SWIFT TASK CONTINUATION MISUSE"). Zero times = the awaiting task hangs forever with no error and no log. Audit every early return, every error branch, and every delegate callback that can fire more than once. Use the Checked variants everywhere except measured hot paths — the Unsafe ones diagnose nothing.
6. Actor state is only consistent between awaits. Actors serialize access but are reentrant: any await inside an actor method lets other calls run and mutate state. Check-then-act across a suspension is a bug. Deduplicate in-flight work by storing the Task handle and returning it, not by flipping an isLoading flag around an await.
7. @unchecked Sendable is a promise you must implement. Legal only when every mutable stored property is reached through one lock (Mutex, NSLock, serial queue) with no path around it, and that lock is documented in the type. Otherwise the compiler stops checking and the race ships. Prefer making the type actually Sendable: let properties of Sendable types, or an actor.
8. Budget the type-checker. One unsolvable expression stalls its whole file. Build with -Xfrontend -warn-long-expression-type-checking=500 -Xfrontend -warn-long-function-bodies=500 (milliseconds) and split whatever it flags — long + chains, mixed numeric literals, and large collection literals without type annotations are the repeat offenders. Annotating one intermediate let routinely takes a multi-second expression under the threshold.

Crash Messages

Swift runtime traps surface as EXC_BREAKPOINT on arm64 and EXC_BAD_INSTRUCTION on x86_64; the human-readable line goes to stderr and lands in crash reports under Application Specific Information. No message at all means it is not a Swift trap — it is a memory error.

Arithmetic Defaults

Swift traps on integer overflow and on impossible conversions in release builds too — arithmetic is a crash surface, not only a correctness one. Choose the operator that states the intent:

Overflow, conversion, floating-point and money depth: numerics.md.

Output Gates

Before emitting Swift code, verify:

• No !, try!, as!, or IUO beyond what force_unwrap_policy allows, and each survivor has a reason a reviewer would accept
• Every escaping closure that touches self has a capture list; every unowned passes the nested-lifetime test (rule 2)
• Every withCheckedContinuation resumes exactly once on every path, thrown errors included
• Nothing blocking (.wait(), Thread.sleep, synchronous file or network I/O) inside an async function (rule 4)
• Mutable global or static state is let, actor-isolated, or explicitly justified — it is a data-race error in language mode 6
• Errors propagated or handled; no empty catch {}, and CancellationError rethrown rather than swallowed (errors.md)
• Every numeric conversion is exactly:/clamping: or provably in range, and no monetary value passes through Double
• New public API follows the naming rules and carries availability when deployment_floor is set (api-design.md)

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/swift/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling — formatter and linter (swift-format vs SwiftLint) and its rule set, whether macro-based libraries are acceptable given their build cost (metaprogramming.md)
• Conventions — default access level, explicit self., doc-comment expectations, one type per file, naming of async vs completion-handler variants
• Platform — toolchain version, OS floors, static vs dynamic linking on Linux, architectures built in CI
• Safety posture — tolerance for try!, fatalError, @unchecked Sendable, unsafe pointers, and wrapping operators, and whether to flag them unprompted or only on review
• Dependencies — Foundation-only vs swift-collections/algorithms/async-algorithms, Combine vs AsyncSequence, the vetted third-party list
• Output format — full files vs minimal diffs, comment density, whether every change ships with a test
• Work order — test-first vs implementation-first, and whether to build and run the suite before handing work back

Traps

Where Experts Disagree

• any existentials vs generics. Existential-first reads better and compiles faster; generic-first runs faster (no boxing, no witness-table lookups) and specializes. The honest boundary is measurement: any for heterogeneous storage and API surfaces, some/generics on hot paths and wherever the concrete type is already known.
• Swift Testing vs XCTest. Swift Testing is the better authoring experience (parameterized cases, #expect with expression capture, in-process parallelism). XCTest still owns UI automation and performance measurement, so mixed suites are normal rather than a smell. Migrating a green XCTest suite for style alone buys nothing.
• How hard to fight for value semantics. One camp makes everything a struct and threads state explicitly; the other accepts reference-typed models where persistence or an Objective-C framework already imposes identity. The line worth defending in either camp: no shared mutable reference type crosses a concurrency boundary without isolation.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/swift (install if the user confirms):

• ios — shipping iOS apps: lifecycle, frameworks, App Store
• xcode — signing, build settings, derived data, IDE-level failures
• macos — macOS system behavior and command-line differences

Feedback

• If useful, star it: https://clawic.com/skills/swift
• Latest version: https://clawic.com/skills/swift

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/swift.