@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-language/SKILL.md

@@ -1,499 +1,459 @@
 ---
 name: swift-language
-description: "Modern Swift language patterns for code outside concurrency and SwiftUI: if/switch expressions, typed throws, result builders, property wrappers, some vs any, guard patterns, Never, Regex builders, modern collection APIs and string interpolation. Use when writing core Swift with generics, protocols, enums, closures or new language features; for deep Codable use swift-codable, for formatting swift-formatstyle, for API naming swift-api-design-guidelines."
+description: "Core Swift 6.3 outside concurrency and SwiftUI: if and switch expressions, typed throws, result builders, property wrappers, some vs any, guard, Never, Regex builders, collection APIs, string interpolation, @c interop, module selectors, performance attributes. Use when writing or reviewing plain Swift with generics, protocols, enums, closures or newer language features. Not for deep Codable, formatting, API naming, concurrency or SwiftUI."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# Swift Language Patterns
+# Swift Language (Swift 6.3)
 
-Core Swift language features and modern syntax patterns targeting Swift 6.3. Covers language constructs, type system features, basic Codable,
-string and collection APIs, basic formatting, C interop (`@c`), module disambiguation (`ModuleName::symbol`), and performance attributes (`@specialized`, `@inline(always)`). For `@c` corrections, enumerate invalid Swift-only signature types: `String`, `Array`, `UnsafeBufferPointer`, closures, and generic placeholders. Route deeper Codable/API decoding to `swift-codable`, detailed formatting/localization to `swift-formatstyle`, API naming to `swift-api-design-guidelines`, concurrency to `swift-concurrency`, and SwiftUI state/view work to `swiftui-patterns`.
+This skill owns the language itself: expressions, the type system, error
+typing, DSL-building features, pattern matching and the standard library
+surface that everyday code touches. It also carries the basics of Codable,
+string and collection APIs, simple formatting, C interop through `@c`, module
+disambiguation with `ModuleName::symbol`, and the performance attributes
+`@specialized` and `@inline(always)`. The attribute details live in
+[references/swift-attributes-interop.md](references/swift-attributes-interop.md).
 
-## Contents
+When a reviewer asks for a `@c` fix, list the Swift-only types that cannot
+appear in the signature: `String`, `Array`, `UnsafeBufferPointer`, closures and
+generic placeholders. Saying "use C types" is not enough.
 
-- [If/Switch Expressions](#ifswitch-expressions)
-- [Typed Throws](#typed-throws)
-- [Result Builders](#result-builders)
-- [Property Wrappers](#property-wrappers)
-- [Opaque and Existential Types](#opaque-and-existential-types)
-- [Guard Patterns](#guard-patterns)
-- [Never Type](#never-type)
-- [Regex Builders](#regex-builders)
-- [Codable Best Practices](#codable-best-practices)
-- [Modern Collection APIs](#modern-collection-apis)
-- [FormatStyle](#formatstyle)
-- [String Interpolation](#string-interpolation)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Hand-offs:
 
-## If/Switch Expressions
+| Topic | Skill |
+|---|---|
+| Codable models, key strategies, date decoding, API payloads | `swift-codable` |
+| Format styles, locale behaviour, localized display | `swift-formatstyle` (with `ios-localization` for market QA) |
+| Naming and argument labels | `swift-api-design-guidelines` |
+| Actors, tasks, isolation, Sendable | `swift-concurrency` |
+| SwiftUI state and view structure | `swiftui-patterns` |
+
+## if and switch as expressions
 
-Swift 5.9+ allows `if` and `switch` as expressions that return values. Use them
-to assign, return, or initialize directly.
+Since Swift 5.9, `if` and `switch` can produce a value directly for an
+assignment, a `return` or an initializer.
 
 ```swift
-// Assign from if expression
-let icon = if isComplete { "checkmark.circle.fill" } else { "circle" }
-
-// Assign from switch expression
-let label = switch status {
-case .draft: "Draft"
-case .published: "Published"
-case .archived: "Archived"
+enum Tier { case free, plus, pro }
+
+func badge(for tier: Tier, trial: Bool) -> String {
+    let base = if trial { "Trial" } else { "Member" }
+    let suffix = switch tier {
+    case .free: ""
+    case .plus: " +"
+    case .pro: " Pro"
+    }
+    return base + suffix
 }
 
-// Works in return position
-func color(for priority: Priority) -> Color {
-    switch priority {
-    case .high: .red
-    case .medium: .orange
-    case .low: .green
+func seatLimit(_ tier: Tier) -> Int {
+    switch tier {
+    case .free: 1
+    case .plus: 5
+    case .pro: 50
     }
 }
 ```
 
-**Rules:**
-- Every branch must produce a value of the same type.
-- Multi-statement branches are not allowed -- each branch is a single expression.
-- Wrap in parentheses when used as a function argument to avoid ambiguity.
+Rules to remember:
 
-## Typed Throws
+- All branches produce one common type.
+- A branch holds exactly one expression. Several statements in a branch are not
+  allowed; fall back to a statement form.
+- Wrap the expression in parentheses when it is passed as a function argument,
+  so the parser does not misread it.
 
-Swift 6+ allows specifying the error type a function throws.
+## Typed throws
 
-```swift
-enum ValidationError: Error {
-    case tooShort, invalidCharacters, alreadyTaken
-}
+Swift 6 lets a function name its error type: `throws(ParseFailure)`. Inside,
+`throw .emptyInput` works as shorthand, and a `catch` block at the call site
+gets `error` already typed as `ParseFailure`, so a `switch` over it can be
+exhaustive with no `as?` cast.
 
-func validate(username: String) throws(ValidationError) -> String {
-    guard username.count >= 3 else { throw .tooShort }
-    guard username.allSatisfy(\.isLetterOrDigit) else { throw .invalidCharacters }
-    return username.lowercased()
+```swift
+enum ParseFailure: Error { case emptyInput, badDigit(Character) }
+
+func parseCode(_ text: String) throws(ParseFailure) -> Int {
+    guard !text.isEmpty else { throw .emptyInput }
+    var value = 0
+    for ch in text {
+        guard let d = ch.wholeNumberValue else { throw .badDigit(ch) }
+        value = value * 10 + d
+    }
+    return value
 }
 
-// Caller gets typed error -- no cast needed
-do {
-    let name = try validate(username: input)
-} catch {
-    // error is ValidationError, not any Error
-    switch error {
-    case .tooShort: print("Too short")
-    case .invalidCharacters: print("Invalid characters")
-    case .alreadyTaken: print("Taken")
+func show(_ text: String) -> String {
+    do {
+        return String(try parseCode(text))
+    } catch {
+        switch error {
+        case .emptyInput: return "missing"
+        case .badDigit(let c): return "bad \(c)"
+        }
     }
 }
 ```
 
-**Rules:**
-- Use `throws(SomeError)` only when callers benefit from exhaustive error
-  handling. For mixed error sources, use untyped `throws`.
-- `throws(Never)` marks a function that syntactically throws but never actually
-  does -- useful in generic contexts.
-- Typed throws propagate: a function calling `throws(A)` and `throws(B)` must
-  itself throw a type that covers both (or use untyped `throws`).
+Guidance:
 
-## Result Builders
+- Reach for `throws(E)` when there is one clear error type and callers gain
+  from handling every case. Code that forwards errors from several unrelated
+  sources stays with plain `throws`.
+- `throws(Never)` spells a function that is declared throwing but cannot
+  throw; it matters mostly in generic code that is parameterised over the
+  error type.
+- Calling a `throws(A)` function and a `throws(B)` function from one body means
+  the outer function must throw a type that covers both, or be untyped.
 
-`@resultBuilder` enables DSL-style syntax. SwiftUI's `@ViewBuilder` is the most
-common example, but you can create custom builders for any domain.
+## Result builders
+
+`@resultBuilder` turns a closure of plain statements into a built value.
+`@ViewBuilder` is the one most people meet first.
 
 ```swift
 @resultBuilder
-struct ArrayBuilder<Element> {
-    static func buildBlock(_ components: [Element]...) -> [Element] {
-        components.flatMap { $0 }
-    }
-    static func buildExpression(_ expression: Element) -> [Element] { [expression] }
-    static func buildOptional(_ component: [Element]?) -> [Element] { component ?? [] }
-    static func buildEither(first component: [Element]) -> [Element] { component }
-    static func buildEither(second component: [Element]) -> [Element] { component }
-    static func buildArray(_ components: [[Element]]) -> [Element] { components.flatMap { $0 } }
+enum LinesBuilder {
+    static func buildExpression(_ line: String) -> [String] { [line] }
+    static func buildBlock(_ parts: [String]...) -> [String] { parts.flatMap { $0 } }
+    static func buildOptional(_ part: [String]?) -> [String] { part ?? [] }
+    static func buildEither(first part: [String]) -> [String] { part }
+    static func buildEither(second part: [String]) -> [String] { part }
+    static func buildArray(_ parts: [[String]]) -> [String] { parts.flatMap { $0 } }
 }
 
-func makeItems(@ArrayBuilder<String> content: () -> [String]) -> [String] { content() }
+func receipt(@LinesBuilder _ body: () -> [String]) -> String {
+    body().joined(separator: "\n")
+}
 
-let items = makeItems {
-    "Always included"
-    if showExtra { "Conditional" }
-    for name in names { name.uppercased() }
+let items = ["tea", "scone"]
+let printed = receipt {
+    "Corner Cafe"
+    for item in items { "- \(item)" }
+    if items.count > 1 { "multi-item order" } else { "single item" }
 }
 ```
 
-**Builder methods:** `buildBlock` (combine statements), `buildExpression` (single value), `buildOptional` (`if` without `else`), `buildEither` (`if/else`), `buildArray` (`for..in`), `buildFinalResult` (optional post-processing).
+What each hook handles:
+
+| Method | Called for |
+|---|---|
+| `buildBlock` | combining the statements of a block |
+| `buildExpression` | lifting one expression into the component type |
+| `buildOptional` | `if` with no `else` |
+| `buildEither(first:)` / `buildEither(second:)` | the two arms of `if`/`else` (and `switch`) |
+| `buildArray` | `for ... in` loops |
+| `buildFinalResult` | optional last step that converts the result |
 
-## Property Wrappers
+More builders: [references/swift-patterns-extended.md](references/swift-patterns-extended.md#result-builders).
 
-Custom `@propertyWrapper` types encapsulate storage and access patterns.
+## Property wrappers
 
 ```swift
 @propertyWrapper
-struct Clamped<Value: Comparable> {
-    private var value: Value
-    let range: ClosedRange<Value>
+struct Bounded<Value: Comparable> {
+    private var stored: Value
+    let limits: ClosedRange<Value>
 
-    var wrappedValue: Value {
-        get { value }
-        set { value = min(max(newValue, range.lowerBound), range.upperBound) }
+    init(wrappedValue: Value, _ limits: ClosedRange<Value>) {
+        self.limits = limits
+        stored = min(max(wrappedValue, limits.lowerBound), limits.upperBound)
     }
 
-    var projectedValue: ClosedRange<Value> { range }
-
-    init(wrappedValue: Value, _ range: ClosedRange<Value>) {
-        self.range = range
-        self.value = min(max(wrappedValue, range.lowerBound), range.upperBound)
+    var wrappedValue: Value {
+        get { stored }
+        set { stored = min(max(newValue, limits.lowerBound), limits.upperBound) }
     }
-}
 
-// Usage
-struct Volume {
-    @Clamped(0...100) var level: Int = 50
+    var projectedValue: ClosedRange<Value> { limits }
 }
 
-var v = Volume()
-v.level = 150   // clamped to 100
-print(v.$level) // projected value: 0...100
-```
-
-**Design rules:**
-- `wrappedValue` is the primary getter/setter.
-- `projectedValue` (accessed via `$property`) provides metadata or bindings.
-- Property wrappers can be composed: `@A @B var x` applies outer wrapper first.
-- Do not use property wrappers when a simple computed property suffices.
-
-## Opaque and Existential Types
-
-### `some Protocol` (Opaque Type)
-
-The caller does not know the concrete type, but the compiler does. The
-underlying type is fixed for a given scope.
-
-```swift
-func makeCollection() -> some Collection<Int> {
-    [1, 2, 3]  // Always returns Array<Int> -- compiler knows the concrete type
+struct Thermostat {
+    @Bounded(10...30) var target: Double = 21
 }
-```
 
-Use `some` for:
-- Return types when you want to hide implementation but preserve type identity.
-- Parameter types (Swift 5.7+): `some P` is shorthand for an unnamed generic
-  parameter such as `<T: P>`.
-
-### `any Protocol` (Existential Type)
-
-An existential box that can hold any conforming type at runtime. It uses dynamic
-dispatch and may allocate when the value does not fit in the inline buffer.
-
-```swift
-func process(items: [any StringProtocol]) {
-    for item in items {
-        print(item.uppercased())
-    }
-}
+var unit = Thermostat()
+unit.target = 45
+let clamped = unit.target
+let window = unit.$target
 ```
 
-### When to choose
-
-| Use `some` | Use `any` |
+- `wrappedValue` is the getter and setter the property exposes.
+- `projectedValue` is what `$name` returns: metadata, a binding, a validity
+  flag.
+- Wrappers stack. With `@Outer @Inner var x`, the outer one wraps the inner
+  one and is applied first.
+- If a computed property would do the job, write the computed property. A
+  wrapper earns its place through reuse or a useful projection.
+
+## some and any
+
+- `some Shape` is an opaque type: the compiler knows the concrete type, the
+  caller does not, and the type stays the same for every return from that
+  scope. `func evens() -> some Collection<Int> { [2, 4, 6] }` hides the array.
+- In parameter position (Swift 5.7+), `some Shape` is shorthand for an
+  anonymous generic parameter `<T: Shape>`.
+- `any Shape` is an existential box. It can hold any conforming value at
+  runtime, calls go through dynamic dispatch, and a value too large for the
+  box's inline storage is heap allocated.
+
+| Pick `some` for | Pick `any` for |
 |---|---|
-| Return type hiding concrete type | Heterogeneous collections |
-| Function parameters (replaces simple generics) | Dynamic type erasure needed |
-| Better performance (static dispatch) | Protocol has `Self` or associated type requirements you need to erase |
+| hiding a return type | mixed-type collections such as `[any Shape]` |
+| simple generic parameters | erasing a type chosen at runtime |
+| static dispatch and speed | working past `Self` or associated-type constraints |
 
-**Rule of thumb:** Default to `some`. Use `any` only when you need a
-heterogeneous collection or runtime type flexibility.
+Start from `some`. Move to `any` only when values of different concrete types
+really have to share one container or the type is decided at runtime.
 
-## Guard Patterns
+## guard
 
-`guard` enforces preconditions and enables early exit. It keeps the happy path
-left-aligned and reduces nesting.
+`guard` states a precondition and leaves early when it fails, so the main path
+stays at the left margin.
 
 ```swift
-func processOrder(_ order: Order?) throws -> Receipt {
-    // Unwrap optionals
-    guard let order else { throw OrderError.missing }
-
-    // Validate conditions
-    guard order.items.isEmpty == false else { throw OrderError.empty }
-    guard order.total > 0 else { throw OrderError.invalidTotal }
-
-    // Boolean checks
-    guard order.isPaid else { throw OrderError.unpaid }
-
-    // Pattern matching
-    guard case .confirmed(let date) = order.status else {
-        throw OrderError.notConfirmed
+enum Shipment { case pending, dispatched(on: Date), lost }
+struct Parcel { var weight: Double; var status: Shipment }
+enum ParcelError: Error { case none, tooHeavy, notDispatched }
+
+func dispatchDate(_ parcel: Parcel?, express: Bool) throws -> Date {
+    guard let parcel else { throw ParcelError.none }
+    guard parcel.weight <= 30 else { throw ParcelError.tooHeavy }
+    guard express else { return .distantFuture }
+    guard case .dispatched(let date) = parcel.status else {
+        throw ParcelError.notDispatched
     }
-
-    return Receipt(order: order, confirmedAt: date)
+    return date
 }
 ```
 
-**Best practices:**
-- Use `guard` for preconditions, `if` for branching logic.
-- Combine related guards: `guard let a, let b else { return }`.
-- The `else` block must exit scope: `return`, `throw`, `continue`, `break`, or
-  `fatalError()`.
-- Use shorthand unwrap: `guard let value else { ... }` (Swift 5.7+).
+- `guard` for preconditions, `if` for genuine branches.
+- Several bindings fit one statement: `guard let host, let port else { return }`.
+- The `else` body has to leave the scope: `return`, `throw`, `continue`,
+  `break`, or a `Never` call such as `fatalError()`.
+- The shorthand `guard let value else` needs Swift 5.7 or later.
 
-## Never Type
+## Never
 
-`Never` is an uninhabited type for code paths that never produce a value. It
-works as Swift's bottom type in expression contexts, but it does not implicitly
-conform to arbitrary protocols or satisfy a generic `T: SomeProtocol`
-constraint. When recommending `Result<T, Never>` or `throws(Never)`, explicitly
-state all three points: uninhabited, bottom-like, and no universal protocol
-conformance.
+When `Never` comes up, say all three things, because each changes what code
+compiles:
 
-```swift
-// Function that terminates the program
-func crashWithDiagnostics(_ message: String) -> Never {
-    let diagnostics = gatherDiagnostics()
-    logger.critical("\(message): \(diagnostics)")
-    fatalError(message)
-}
+1. It is uninhabited: no value of type `Never` can exist.
+2. It behaves like a bottom type in expressions: a call returning `Never` can
+   stand where any type is expected.
+3. It does not conform to arbitrary protocols, so it does not satisfy an
+   arbitrary `T: SomeProtocol` constraint on its own.
+
+This applies whenever you recommend `Result<T, Never>` or `throws(Never)`.
 
-enum Result<Success, Failure: Error> {
-    case success(Success)
-    case failure(Failure)
+```swift
+func halt(_ reason: String, context: [String: String]) -> Never {
+    let summary = context.map { "\($0.key)=\($0.value)" }.sorted().joined(separator: " ")
+    print("fatal: \(reason) \(summary)")
+    fatalError(reason)
 }
-// Result<String, Never> -- a result that can never fail
 
-// Exhaustive switch: no default needed since Never has no cases
-func handle(_ result: Result<String, Never>) {
-    switch result {
-    case .success(let value): print(value)
-    // No .failure case needed -- compiler knows it's impossible
-    }
+let greeting: Result<String, Never> = .success("hello")
+switch greeting {
+case .success(let text): print(text)
 }
 ```
 
-## Regex Builders
+A function returning `Never` does not come back. A `Result` whose failure type
+is `Never` cannot fail, so the `switch` needs only `.success` and no `default`.
+
+## Regex builders
 
-Swift 5.7+ Regex builder DSL provides compile-time checked, readable patterns.
+`RegexBuilder` (Swift 5.7+, imported next to Foundation) writes patterns as
+readable, compiler-checked Swift with typed captures.
 
 ```swift
 import Foundation
 import RegexBuilder
 
-// Parse "2024-03-15" into components
-let dateRegex = Regex {
-    Capture { /\d{4}/ }; "-"; Capture { /\d{2}/ }; "-"; Capture { /\d{2}/ }
+let clock = Regex {
+    Capture { /\d{2}/ }
+    ":"
+    Capture { /\d{2}/ }
 }
-
-if let match = "2024-03-15".firstMatch(of: dateRegex) {
-    let (_, year, month, day) = match.output
-    _ = (year, month, day)
+if let hit = "Doors open 19:45".firstMatch(of: clock) {
+    let (_, hour, minute) = hit.output
+    print(hour, minute)
 }
 
-// TryCapture with transform
-let priceRegex = Regex {
-    "$"
-    TryCapture { OneOrMore(.digit); "."; Repeat(.digit, count: 2) }
-        transform: { Decimal(string: String($0)) }
+let price = Regex {
+    "EUR "
+    TryCapture {
+        OneOrMore(.digit)
+        "."
+        Repeat(.digit, count: 2)
+    } transform: { Decimal(string: String($0)) }
 }
 ```
 
-**When to use builder vs. literal:**
-- Builder: complex patterns, reusable components, strong typing on captures.
-- Literal (`/pattern/`): simple patterns, familiarity with regex syntax.
-- Both can be mixed: embed `/.../` literals inside builder blocks.
-
-## Codable Best Practices
+Use the builder when a pattern is long, reused, or needs typed captures. A
+short one-off pattern reads better as a literal such as `/\d+/`, and literals
+can be dropped into a builder where that helps. More in
+[references/swift-patterns-extended.md](references/swift-patterns-extended.md#advanced-regex).
 
-### Custom CodingKeys
-
-Rename keys without writing a custom decoder:
+## Codable basics
 
 ```swift
-struct User: Codable {
-    let id: Int
-    let displayName: String
-    let avatarURL: URL
+struct Venue: Codable {
+    var venueName: String
+    var seatCount: Int
+    var isOutdoor: Bool
+    var city: String
 
     enum CodingKeys: String, CodingKey {
-        case id
-        case displayName = "display_name"
-        case avatarURL = "avatar_url"
+        case venueName = "venue_name", seatCount = "seat_count", isOutdoor = "is_outdoor", location
     }
-}
-```
-
-### Custom Decoding
-
-Handle mismatched types, defaults, and transformations:
-
-```swift
-struct Item: Decodable {
-    let name: String
-    let quantity: Int
-    let isActive: Bool
+    enum LocationKeys: String, CodingKey { case city }
 
     init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        name = try container.decode(String.self, forKey: .name)
-        quantity = try container.decodeIfPresent(Int.self, forKey: .quantity) ?? 0
-        if let boolValue = try? container.decode(Bool.self, forKey: .isActive) {
-            isActive = boolValue
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        venueName = try c.decode(String.self, forKey: .venueName)
+        seatCount = try c.decodeIfPresent(Int.self, forKey: .seatCount) ?? 0
+        if let flag = try? c.decode(Bool.self, forKey: .isOutdoor) {
+            isOutdoor = flag
         } else {
-            isActive = (try container.decode(String.self, forKey: .isActive)).lowercased() == "true"
+            isOutdoor = (try c.decodeIfPresent(String.self, forKey: .isOutdoor)) == "true"
         }
-    }
-    enum CodingKeys: String, CodingKey { case name, quantity; case isActive = "is_active" }
-}
-```
-
-### Nested Containers
-
-Flatten nested JSON into a flat Swift struct:
-
-```swift
-// JSON: { "id": 1, "metadata": { "created_at": "...", "tags": [...] } }
-struct Record: Decodable {
-    let id: Int
-    let createdAt: String
-    let tags: [String]
-
-    enum CodingKeys: String, CodingKey {
-        case id, metadata
+        let place = try c.nestedContainer(keyedBy: LocationKeys.self, forKey: .location)
+        city = try place.decode(String.self, forKey: .city)
     }
 
-    enum MetadataKeys: String, CodingKey {
-        case createdAt = "created_at"
-        case tags
-    }
-
-    init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        id = try container.decode(Int.self, forKey: .id)
-        let metadata = try container.nestedContainer(
-            keyedBy: MetadataKeys.self, forKey: .metadata)
-        createdAt = try metadata.decode(String.self, forKey: .createdAt)
-        tags = try metadata.decode([String].self, forKey: .tags)
+    func encode(to encoder: Encoder) throws {
+        var c = encoder.container(keyedBy: CodingKeys.self)
+        try c.encode(venueName, forKey: .venueName)
+        try c.encode(seatCount, forKey: .seatCount)
+        try c.encode(isOutdoor, forKey: .isOutdoor)
+        var place = c.nestedContainer(keyedBy: LocationKeys.self, forKey: .location)
+        try place.encode(city, forKey: .city)
     }
 }
 ```
 
-See [references/swift-patterns-extended.md](references/swift-patterns-extended.md) for additional Codable patterns
-(enums with associated values, date strategies, unkeyed containers).
+- A `CodingKeys: String, CodingKey` enum renames snake_case keys without a
+  custom decoder.
+- A custom `init(from:)` covers defaults (`decodeIfPresent(...) ?? value`) and
+  type mismatches, here a flag that sometimes arrives as the string `"true"`.
+- `nestedContainer(keyedBy:forKey:)` flattens a nested JSON object into flat
+  properties using a second key enum.
 
-## Modern Collection APIs
+Enums with associated values, date strategies and unkeyed containers are in
+[references/swift-patterns-extended.md](references/swift-patterns-extended.md#codable).
+Anything beyond this goes to `swift-codable`.
 
-Prefer these modern APIs over manual loops:
+## Collection APIs
 
 ```swift
-let numbers = [1, 2, 3, 4, 5, 6, 7, 8]
-
-// count(where:) -- use instead of .filter { }.count
-let evenCount = numbers.count(where: { $0.isMultiple(of: 2) })
-
-// contains(where:) -- short-circuits on first match
-let hasNegative = numbers.contains(where: { $0 < 0 })
-
-// first(where:) / last(where:)
-let firstEven = numbers.first(where: { $0.isMultiple(of: 2) })
-
-// String replacing() -- Swift 5.7+, returns new string
-let cleaned = rawText.replacing(/\s+/, with: " ")
-let snakeCase = name.replacing("_", with: " ")
-
-// compactMap -- unwrap optionals from a transform
-let ids = strings.compactMap { Int($0) }
-
-// flatMap -- flatten nested collections
-let allTags = articles.flatMap(\.tags)
-
-// Dictionary(grouping:by:)
-let byCategory = Dictionary(grouping: items, by: \.category)
-
-// reduce(into:) -- efficient accumulation
-let freq = words.reduce(into: [:]) { counts, word in
-    counts[word, default: 0] += 1
-}
+let scores = [72, 95, 40, 88]
+let passed = scores.count(where: { $0 >= 50 })
+let hasPerfect = scores.contains(where: { $0 == 100 })
+let firstFail = scores.first(where: { $0 < 50 })
+let lastHigh = scores.last(where: { $0 > 80 })
+
+let slug = "Summer Sale 2026".replacing(" ", with: "-")
+let digitsHidden = "PIN 4821".replacing(/\d/, with: "*")
+
+struct Post { var tags: [String]; var author: String? }
+let posts = [Post(tags: ["swift"], author: "ana"), Post(tags: ["ios", "swift"], author: nil)]
+let authors = posts.compactMap(\.author)
+let allTags = posts.flatMap(\.tags)
+let byFirstTag = Dictionary(grouping: posts, by: { $0.tags.first ?? "" })
+let tagCounts = allTags.reduce(into: [:]) { tally, tag in tally[tag, default: 0] += 1 }
 ```
 
-## FormatStyle
+- `count(where:)` replaces `filter { }.count` without building an array.
+- `contains(where:)` stops at the first match.
+- `String.replacing(_:with:)` (Swift 5.7+) returns a new string and takes a
+  string or a regex.
+- `compactMap` drops `nil`; `flatMap(\.tags)` flattens nested arrays.
+- `Dictionary(grouping:by:)` buckets values by a key.
+- `reduce(into:)` mutates one accumulator instead of copying on every step.
 
-Use `.formatted()` instead of `DateFormatter`/`NumberFormatter`. It is
-type-safe, localized, and concise.
+## Formatting basics
 
-```swift
-// Dates
-let now = Date.now
-now.formatted()                                       // "3/15/2024, 2:30 PM"
-now.formatted(date: .abbreviated, time: .shortened)   // "Mar 15, 2024, 2:30 PM"
-now.formatted(.dateTime.year().month().day())          // "Mar 15, 2024"
-now.formatted(.relative(presentation: .named))        // "yesterday"
-
-// Numbers
-let price = 42.5
-price.formatted(.currency(code: "USD"))               // "$42.50"
-price.formatted(.percent)                             // "4,250%"
-(1_000_000).formatted(.number.notation(.compactName)) // "1M"
-
-// Measurements
-let distance = Measurement(value: 5, unit: UnitLength.kilometers)
-distance.formatted(.measurement(width: .abbreviated)) // "5 km"
-
-// Duration (Swift 5.7+)
-let duration = Duration.seconds(3661)
-duration.formatted(.time(pattern: .hourMinuteSecond)) // "1:01:01"
-
-// Byte counts
-Int64(1_500_000).formatted(.byteCount(style: .file)) // "1.5 MB"
-
-// Lists
-["Alice", "Bob", "Carol"].formatted(.list(type: .and)) // "Alice, Bob, and Carol"
-```
+Prefer `.formatted()` to `DateFormatter` and `NumberFormatter`: it is typed,
+localized and short.
 
-**Parsing:** `FormatStyle` also supports parsing:
 ```swift
-let value = try Decimal("$42.50", format: .currency(code: "USD"))
-let date = try Date("Mar 15, 2024", strategy: .dateTime.month().day().year())
+import Foundation
+
+let now = Date()
+now.formatted()
+now.formatted(date: .abbreviated, time: .shortened)
+now.formatted(.dateTime.year().month().day())
+now.addingTimeInterval(-3600).formatted(.relative(presentation: .named))
+
+19.99.formatted(.currency(code: "EUR"))
+0.425.formatted(.percent)
+42.5.formatted(.percent)
+2_400_000.formatted(.number.notation(.compactName))
+Measurement(value: 12, unit: UnitLength.kilometers).formatted(.measurement(width: .abbreviated))
+Duration.seconds(4000).formatted(.time(pattern: .hourMinuteSecond))
+Int64(5_300_000).formatted(.byteCount(style: .file))
+["oat", "rye", "spelt"].formatted(.list(type: .and))
+
+let cost = try Decimal("EUR 42.50", format: .currency(code: "EUR"))
+let day = try Date("Mar 4, 2026", strategy: .dateTime.month().day().year())
 ```
 
-## String Interpolation
-
-Extend `DefaultStringInterpolation` for domain-specific formatting. Use `"""` for multi-line strings (indentation is relative to the closing `"""`). See [references/swift-patterns-extended.md](references/swift-patterns-extended.md) for custom interpolation examples.
-
-## Common Mistakes
-
-1. **Using `any` when `some` works.** Default to `some` for return types and
-   parameters. `any` has runtime overhead and loses type information.
-2. **Manual loops instead of collection APIs.** Use `count(where:)`,
-   `contains(where:)`, `compactMap`, `flatMap` instead of manual iteration.
-3. **`DateFormatter` instead of FormatStyle.** `.formatted()` is simpler,
-   type-safe, and handles localization automatically.
-4. **Force-unwrapping Codable decodes.** Use `decodeIfPresent` with defaults
-   for optional or missing keys.
-5. **Nested if-let chains.** Use `guard let` for preconditions to keep the
-   happy path at the top level.
-6. **Invalid `@c` signatures.** Name valid C types and explicitly reject:
-   `String`, `Array`, `UnsafeBufferPointer`, closures, generic placeholders.
-7. **Ignoring typed throws.** When a function has a single, clear error type,
-   typed throws give callers exhaustive switch without casting.
-8. **Overusing property wrappers.** A computed property is simpler when there
-   is no reuse or projected value needed.
-9. **Underspecifying `Never`.** For `Result<T, Never>` or `throws(Never)`, say:
-   uninhabited, bottom-like, and not arbitrary `T: P` protocol conformance.
-10. **Owning deep formatting/localization.** Use `swift-formatstyle` for detailed
-    formatting and `ios-localization` for market/localized-display QA.
-
-## Review Checklist
-
-- [ ] `some` used for opaque returns and Swift 5.7+ generic-parameter shorthand
+`.percent` multiplies by 100, so `42.5` prints as `4,250%`; pass `0.425` for
+42.5%. `.compactName` turns 2,400,000 into `2.4M`. `Duration.formatted` needs
+Swift 5.7+. Everything past these basics, including locale behaviour and
+custom styles in depth, belongs to `swift-formatstyle`.
+
+## String interpolation
+
+Extending `DefaultStringInterpolation` gives domain-specific `\(...)` forms;
+see [references/swift-patterns-extended.md](references/swift-patterns-extended.md#string-interpolation).
+In a `"""` multi-line string, indentation is measured from the closing
+delimiter, so align the closing quotes with the text you want flush left.
+
+## Common mistakes
+
+1. `any` where `some` would do: adds boxing and dynamic dispatch and throws
+   away type information.
+2. Hand-written loops where `count(where:)`, `contains(where:)`, `compactMap`
+   or `flatMap` say it directly.
+3. New `DateFormatter` code instead of format styles.
+4. Force-unwrapping decoded values; use `decodeIfPresent` with a default.
+5. Nested `if let` pyramids; use `guard let`.
+6. Accepting an invalid `@c` signature. Name the C-compatible types that are
+   allowed and reject `String`, `Array`, `UnsafeBufferPointer`, closures and
+   generic placeholders.
+7. Plain `throws` when a single error type exists and callers would switch on
+   it.
+8. A property wrapper with no reuse and no projection.
+9. Describing `Never` loosely; state uninhabited, bottom-like and no universal
+   conformance.
+10. Taking over deep formatting or localization work that belongs to
+    `swift-formatstyle` and `ios-localization`.
+
+## Review checklist
+
+- [ ] `some` used for opaque returns and as parameter shorthand
 - [ ] `guard` for preconditions; collection APIs instead of manual loops
-- [ ] `.formatted()` used instead of `DateFormatter`/`NumberFormatter`
-- [ ] Codable types use `CodingKeys` for API mapping; `decodeIfPresent` with defaults for optional fields
-- [ ] if/switch expressions for conditional assignment; property wrappers have clear reuse justification
-- [ ] Regex builder used for complex patterns (literal OK for simple ones)
-- [ ] Typed throws used when callers benefit from exhaustive error handling
-- [ ] `@c` corrections enumerate rejected Swift-only types by name
-- [ ] `Never` guidance says uninhabited, bottom-like, and not arbitrary `T: P` protocol conformance
-- [ ] deep Codable, formatting/localization, naming, concurrency, and SwiftUI work routed to sibling skills
+- [ ] `.formatted()` instead of formatter objects
+- [ ] `CodingKeys` for renames; `decodeIfPresent` with defaults
+- [ ] `if`/`switch` expressions for conditional assignment; wrappers justified
+      by reuse
+- [ ] Regex builder for complex patterns, literals for simple ones
+- [ ] typed throws where exhaustive handling helps callers
+- [ ] `@c` corrections list the rejected Swift-only types
+- [ ] `Never` guidance states all three properties
+- [ ] deep Codable, formatting and localization, naming, concurrency and
+      SwiftUI work sent to the sibling skills
+
 ## References
 
-- Extended patterns and Codable examples: [references/swift-patterns-extended.md](references/swift-patterns-extended.md)
-- Attributes and C interop: [references/swift-attributes-interop.md](references/swift-attributes-interop.md)
+- [references/swift-patterns-extended.md](references/swift-patterns-extended.md):
+  Codable edge cases, builders, wrappers, advanced Regex, custom format
+  styles, Swift Algorithms, complex `guard`, typed throws in protocols, custom
+  interpolation, advanced `Never`.
+- [references/swift-attributes-interop.md](references/swift-attributes-interop.md):
+  `@c`, module selectors, `@specialized`, `@inline(always)`, `@export`,
+  `@section` and `@used`.