@baselane/packs 0.1.5 → 0.1.6

package/packs/full-harness/rendered/.claude/skills/strategic-compact/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: strategic-compact
+description: Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## When to Activate
+
+- Running long sessions that approach context limits (200K+ tokens)
+- Working on multi-phase tasks (research → plan → implement → test)
+- Switching between unrelated tasks within the same session
+- After completing a major milestone and starting new work
+- When responses slow down or become less coherent (context pressure)
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+- Often mid-task, losing important context
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step operations
+
+Strategic compaction at logical boundaries:
+- **After exploration, before execution** — Compact research context, keep implementation plan
+- **After completing a milestone** — Fresh start for next phase
+- **Before major context shifts** — Clear exploration context before different task
+
+## How It Works
+
+The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and combines two signals:
+
+1. **Context size (primary)** — Reads the latest `usage` record from the session transcript (`transcript_path` in the hook payload) and sums `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` (the true context size of the turn). Suggests `/compact` at a window-scaled threshold — 160k tokens on a 200k window, 250k on a 1M window (detected from a `[1m]` model marker, or inferred when observed tokens already exceed 200k) — and re-reminds after every additional 60k tokens of context growth
+2. **Tool-call count (secondary)** — Counts tool invocations in session; suggests at a configurable threshold (default: 50 calls), then every 25 calls after
+
+Tool count alone is a weak proxy for window pressure: a few large file reads or MCP responses can fill the window in very few calls, while many tiny calls can cross 50 with a near-empty window. The context-size signal fires when it actually matters.
+
+## Hook Setup
+
+**Installed as a plugin?** No setup is needed. The plugin's `hooks/hooks.json` already registers `suggest-compact.js` (hook id `pre:edit-write:suggest-compact`, active in the `standard` and `strict` hook profiles). Do not copy the block below into `~/.claude/settings.json` — `~/.claude/scripts/` does not exist on plugin installs, and duplicating a plugin hook causes double execution.
+
+**If installed manually** (`./install.sh`), add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
+      }
+    ]
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
+- `COMPACT_CONTEXT_THRESHOLD` — Context tokens before the context-size suggestion (default: 160000 on a 200k window, 250000 on a 1M window; `0` disables the context signal)
+- `COMPACT_CONTEXT_INTERVAL` — Additional context tokens before the suggestion repeats (default: 60000)
+- `COMPACT_STATE_TTL_DAYS` — Days before stale per-session state files in the temp dir are swept (default: 14)
+
+## Compaction Decision Guide
+
+Use this table to decide when to compact:
+
+| Phase Transition | Compact? | Why |
+|-----------------|----------|-----|
+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
+
+## What Survives Compaction
+
+Understanding what persists helps you compact with confidence:
+
+| Persists | Lost |
+|----------|------|
+| CLAUDE.md instructions | Intermediate reasoning and analysis |
+| TodoWrite task list | File contents you previously read |
+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
+| Git state (commits, branches) | Tool call history and counts |
+| Files on disk | Nuanced user preferences stated verbally |
+
+## Best Practices
+
+1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
+2. **Compact after debugging** — Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** — Preserve context for related changes
+4. **Read the suggestion** — The hook tells you *when*, you decide *if*
+5. **Write before compacting** — Save important context to files or memory before compacting
+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
+
+## Token Optimization Patterns
+
+### Trigger-Table Lazy Loading
+Instead of loading full skill content at session start, use a trigger table that maps keywords to skill paths. Skills load only when triggered, reducing baseline context by 50%+:
+
+| Trigger | Skill | Load When |
+|---------|-------|-----------|
+| "test", "tdd", "coverage" | tdd-workflow | User mentions testing |
+| "security", "auth", "xss" | security-review | Security-related work |
+| "deploy", "ci/cd" | deployment-patterns | Deployment context |
+
+### Context Composition Awareness
+Monitor what's consuming your context window:
+- **CLAUDE.md files** — Always loaded, keep lean
+- **Loaded skills** — Each skill adds 1-5K tokens
+- **Conversation history** — Grows with each exchange
+- **Tool results** — File reads, search results add bulk
+
+### Duplicate Instruction Detection
+Common sources of duplicate context:
+- Same rules in both `~/.claude/rules/` and project `.claude/rules/`
+- Skills that repeat CLAUDE.md instructions
+- Multiple skills covering overlapping domains
+
+### Context Optimization Tools
+- `token-optimizer` MCP — Automated 95%+ token reduction via content deduplication
+- `context-mode` — Context virtualization (315KB to 5.4KB demonstrated)
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
+- Memory persistence hooks — For state that survives compaction
+- `continuous-learning` skill — Extracts patterns before session ends

package/packs/full-harness/rendered/.claude/skills/swift-actor-persistence/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: swift-actor-persistence
+description: Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design.
+---
+
+# Swift Actors for Thread-Safe Persistence
+
+Patterns for building thread-safe data persistence layers using Swift actors. Combines in-memory caching with file-backed storage, leveraging the actor model to eliminate data races at compile time.
+
+## When to Activate
+
+- Building a data persistence layer in Swift 5.5+
+- Need thread-safe access to shared mutable state
+- Want to eliminate manual synchronization (locks, DispatchQueues)
+- Building offline-first apps with local storage
+
+## Core Pattern
+
+### Actor-Based Repository
+
+The actor model guarantees serialized access — no data races, enforced by the compiler.
+
+```swift
+public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
+    private var cache: [String: T] = [:]
+    private let fileURL: URL
+
+    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {
+        self.fileURL = directory.appendingPathComponent(filename)
+        // Synchronous load during init (actor isolation not yet active)
+        self.cache = Self.loadSynchronously(from: fileURL)
+    }
+
+    // MARK: - Public API
+
+    public func save(_ item: T) throws {
+        cache[item.id] = item
+        try persistToFile()
+    }
+
+    public func delete(_ id: String) throws {
+        cache[id] = nil
+        try persistToFile()
+    }
+
+    public func find(by id: String) -> T? {
+        cache[id]
+    }
+
+    public func loadAll() -> [T] {
+        Array(cache.values)
+    }
+
+    // MARK: - Private
+
+    private func persistToFile() throws {
+        let data = try JSONEncoder().encode(Array(cache.values))
+        try data.write(to: fileURL, options: .atomic)
+    }
+
+    private static func loadSynchronously(from url: URL) -> [String: T] {
+        guard let data = try? Data(contentsOf: url),
+              let items = try? JSONDecoder().decode([T].self, from: data) else {
+            return [:]
+        }
+        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })
+    }
+}
+```
+
+### Usage
+
+All calls are automatically async due to actor isolation:
+
+```swift
+let repository = LocalRepository<Question>()
+
+// Read — fast O(1) lookup from in-memory cache
+let question = await repository.find(by: "q-001")
+let allQuestions = await repository.loadAll()
+
+// Write — updates cache and persists to file atomically
+try await repository.save(newQuestion)
+try await repository.delete("q-001")
+```
+
+### Combining with @Observable ViewModel
+
+```swift
+@Observable
+final class QuestionListViewModel {
+    private(set) var questions: [Question] = []
+    private let repository: LocalRepository<Question>
+
+    init(repository: LocalRepository<Question> = LocalRepository()) {
+        self.repository = repository
+    }
+
+    func load() async {
+        questions = await repository.loadAll()
+    }
+
+    func add(_ question: Question) async throws {
+        try await repository.save(question)
+        questions = await repository.loadAll()
+    }
+}
+```
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Actor (not class + lock) | Compiler-enforced thread safety, no manual synchronization |
+| In-memory cache + file persistence | Fast reads from cache, durable writes to disk |
+| Synchronous init loading | Avoids async initialization complexity |
+| Dictionary keyed by ID | O(1) lookups by identifier |
+| Generic over `Codable & Identifiable` | Reusable across any model type |
+| Atomic file writes (`.atomic`) | Prevents partial writes on crash |
+
+## Best Practices
+
+- **Use `Sendable` types** for all data crossing actor boundaries
+- **Keep the actor's public API minimal** — only expose domain operations, not persistence details
+- **Use `.atomic` writes** to prevent data corruption if the app crashes mid-write
+- **Load synchronously in `init`** — async initializers add complexity with minimal benefit for local files
+- **Combine with `@Observable`** ViewModels for reactive UI updates
+
+## Anti-Patterns to Avoid
+
+- Using `DispatchQueue` or `NSLock` instead of actors for new Swift concurrency code
+- Exposing the internal cache dictionary to external callers
+- Making the file URL configurable without validation
+- Forgetting that all actor method calls are `await` — callers must handle async context
+- Using `nonisolated` to bypass actor isolation (defeats the purpose)
+
+## When to Use
+
+- Local data storage in iOS/macOS apps (user data, settings, cached content)
+- Offline-first architectures that sync to a server later
+- Any shared mutable state that multiple parts of the app access concurrently
+- Replacing legacy `DispatchQueue`-based thread safety with modern Swift concurrency

package/packs/full-harness/rendered/.claude/skills/swift-concurrency-6-2/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: swift-concurrency-6-2
+description: Swift 6.2 Approachable Concurrency — single-threaded by default, @concurrent for explicit background offloading, isolated conformances for main actor types.
+---
+
+# Swift 6.2 Approachable Concurrency
+
+Patterns for adopting Swift 6.2's concurrency model where code runs single-threaded by default and concurrency is introduced explicitly. Eliminates common data-race errors without sacrificing performance.
+
+## When to Activate
+
+- Migrating Swift 5.x or 6.0/6.1 projects to Swift 6.2
+- Resolving data-race safety compiler errors
+- Designing MainActor-based app architecture
+- Offloading CPU-intensive work to background threads
+- Implementing protocol conformances on MainActor-isolated types
+- Enabling Approachable Concurrency build settings in Xcode 26
+
+## Core Problem: Implicit Background Offloading
+
+In Swift 6.1 and earlier, async functions could be implicitly offloaded to background threads, causing data-race errors even in seemingly safe code:
+
+```swift
+// Swift 6.1: ERROR
+@MainActor
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+
+    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
+        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
+
+        // Error: Sending 'self.photoProcessor' risks causing data races
+        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
+    }
+}
+```
+
+Swift 6.2 fixes this: async functions stay on the calling actor by default.
+
+```swift
+// Swift 6.2: OK — async stays on MainActor, no data race
+@MainActor
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+
+    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
+        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
+        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
+    }
+}
+```
+
+## Core Pattern — Isolated Conformances
+
+MainActor types can now conform to non-isolated protocols safely:
+
+```swift
+protocol Exportable {
+    func export()
+}
+
+// Swift 6.1: ERROR — crosses into main actor-isolated code
+// Swift 6.2: OK with isolated conformance
+extension StickerModel: @MainActor Exportable {
+    func export() {
+        photoProcessor.exportAsPNG()
+    }
+}
+```
+
+The compiler ensures the conformance is only used on the main actor:
+
+```swift
+// OK — ImageExporter is also @MainActor
+@MainActor
+struct ImageExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        items.append(item)  // Safe: same actor isolation
+    }
+}
+
+// ERROR — nonisolated context can't use MainActor conformance
+nonisolated struct ImageExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        items.append(item)  // Error: Main actor-isolated conformance cannot be used here
+    }
+}
+```
+
+## Core Pattern — Global and Static Variables
+
+Protect global/static state with MainActor:
+
+```swift
+// Swift 6.1: ERROR — non-Sendable type may have shared mutable state
+final class StickerLibrary {
+    static let shared: StickerLibrary = .init()  // Error
+}
+
+// Fix: Annotate with @MainActor
+@MainActor
+final class StickerLibrary {
+    static let shared: StickerLibrary = .init()  // OK
+}
+```
+
+### MainActor Default Inference Mode
+
+Swift 6.2 introduces a mode where MainActor is inferred by default — no manual annotations needed:
+
+```swift
+// With MainActor default inference enabled:
+final class StickerLibrary {
+    static let shared: StickerLibrary = .init()  // Implicitly @MainActor
+}
+
+final class StickerModel {
+    let photoProcessor: PhotoProcessor
+    var selection: [PhotosPickerItem]  // Implicitly @MainActor
+}
+
+extension StickerModel: Exportable {  // Implicitly @MainActor conformance
+    func export() {
+        photoProcessor.exportAsPNG()
+    }
+}
+```
+
+This mode is opt-in and recommended for apps, scripts, and other executable targets.
+
+## Core Pattern — @concurrent for Background Work
+
+When you need actual parallelism, explicitly offload with `@concurrent`:
+
+> **Important:** This example requires Approachable Concurrency build settings — SE-0466 (MainActor default isolation) and SE-0461 (NonisolatedNonsendingByDefault). With these enabled, `extractSticker` stays on the caller's actor, making mutable state access safe. **Without these settings, this code has a data race** — the compiler will flag it.
+
+```swift
+nonisolated final class PhotoProcessor {
+    private var cachedStickers: [String: Sticker] = [:]
+
+    func extractSticker(data: Data, with id: String) async -> Sticker {
+        if let sticker = cachedStickers[id] {
+            return sticker
+        }
+
+        let sticker = await Self.extractSubject(from: data)
+        cachedStickers[id] = sticker
+        return sticker
+    }
+
+    // Offload expensive work to concurrent thread pool
+    @concurrent
+    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
+}
+
+// Callers must await
+let processor = PhotoProcessor()
+processedPhotos[item.id] = await processor.extractSticker(data: data, with: item.id)
+```
+
+To use `@concurrent`:
+1. Mark the containing type as `nonisolated`
+2. Add `@concurrent` to the function
+3. Add `async` if not already asynchronous
+4. Add `await` at call sites
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Single-threaded by default | Most natural code is data-race free; concurrency is opt-in |
+| Async stays on calling actor | Eliminates implicit offloading that caused data-race errors |
+| Isolated conformances | MainActor types can conform to protocols without unsafe workarounds |
+| `@concurrent` explicit opt-in | Background execution is a deliberate performance choice, not accidental |
+| MainActor default inference | Reduces boilerplate `@MainActor` annotations for app targets |
+| Opt-in adoption | Non-breaking migration path — enable features incrementally |
+
+## Migration Steps
+
+1. **Enable in Xcode**: Swift Compiler > Concurrency section in Build Settings
+2. **Enable in SPM**: Use `SwiftSettings` API in package manifest
+3. **Use migration tooling**: Automatic code changes via swift.org/migration
+4. **Start with MainActor defaults**: Enable inference mode for app targets
+5. **Add `@concurrent` where needed**: Profile first, then offload hot paths
+6. **Test thoroughly**: Data-race issues become compile-time errors
+
+## Best Practices
+
+- **Start on MainActor** — write single-threaded code first, optimize later
+- **Use `@concurrent` only for CPU-intensive work** — image processing, compression, complex computation
+- **Enable MainActor inference mode** for app targets that are mostly single-threaded
+- **Profile before offloading** — use Instruments to find actual bottlenecks
+- **Protect globals with MainActor** — global/static mutable state needs actor isolation
+- **Use isolated conformances** instead of `nonisolated` workarounds or `@Sendable` wrappers
+- **Migrate incrementally** — enable features one at a time in build settings
+
+## Anti-Patterns to Avoid
+
+- Applying `@concurrent` to every async function (most don't need background execution)
+- Using `nonisolated` to suppress compiler errors without understanding isolation
+- Keeping legacy `DispatchQueue` patterns when actors provide the same safety
+- Skipping `model.availability` checks in concurrency-related Foundation Models code
+- Fighting the compiler — if it reports a data race, the code has a real concurrency issue
+- Assuming all async code runs in the background (Swift 6.2 default: stays on calling actor)
+
+## When to Use
+
+- All new Swift 6.2+ projects (Approachable Concurrency is the recommended default)
+- Migrating existing apps from Swift 5.x or 6.0/6.1 concurrency
+- Resolving data-race safety compiler errors during Xcode 26 adoption
+- Building MainActor-centric app architectures (most UI apps)
+- Performance optimization — offloading specific heavy computations to background

package/packs/full-harness/rendered/.claude/skills/swift-protocol-di-testing/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: swift-protocol-di-testing
+description: Protocol-based dependency injection for testable Swift code — mock file system, network, and external APIs using focused protocols and Swift Testing.
+---
+
+# Swift Protocol-Based Dependency Injection for Testing
+
+Patterns for making Swift code testable by abstracting external dependencies (file system, network, iCloud) behind small, focused protocols. Enables deterministic tests without I/O.
+
+## When to Activate
+
+- Writing Swift code that accesses file system, network, or external APIs
+- Need to test error handling paths without triggering real failures
+- Building modules that work across environments (app, test, SwiftUI preview)
+- Designing testable architecture with Swift concurrency (actors, Sendable)
+
+## Core Pattern
+
+### 1. Define Small, Focused Protocols
+
+Each protocol handles exactly one external concern.
+
+```swift
+// File system access
+public protocol FileSystemProviding: Sendable {
+    func containerURL(for purpose: Purpose) -> URL?
+}
+
+// File read/write operations
+public protocol FileAccessorProviding: Sendable {
+    func read(from url: URL) throws -> Data
+    func write(_ data: Data, to url: URL) throws
+    func fileExists(at url: URL) -> Bool
+}
+
+// Bookmark storage (e.g., for sandboxed apps)
+public protocol BookmarkStorageProviding: Sendable {
+    func saveBookmark(_ data: Data, for key: String) throws
+    func loadBookmark(for key: String) throws -> Data?
+}
+```
+
+### 2. Create Default (Production) Implementations
+
+```swift
+public struct DefaultFileSystemProvider: FileSystemProviding {
+    public init() {}
+
+    public func containerURL(for purpose: Purpose) -> URL? {
+        FileManager.default.url(forUbiquityContainerIdentifier: nil)
+    }
+}
+
+public struct DefaultFileAccessor: FileAccessorProviding {
+    public init() {}
+
+    public func read(from url: URL) throws -> Data {
+        try Data(contentsOf: url)
+    }
+
+    public func write(_ data: Data, to url: URL) throws {
+        try data.write(to: url, options: .atomic)
+    }
+
+    public func fileExists(at url: URL) -> Bool {
+        FileManager.default.fileExists(atPath: url.path)
+    }
+}
+```
+
+### 3. Create Mock Implementations for Testing
+
+```swift
+public final class MockFileAccessor: FileAccessorProviding, @unchecked Sendable {
+    public var files: [URL: Data] = [:]
+    public var readError: Error?
+    public var writeError: Error?
+
+    public init() {}
+
+    public func read(from url: URL) throws -> Data {
+        if let error = readError { throw error }
+        guard let data = files[url] else {
+            throw CocoaError(.fileReadNoSuchFile)
+        }
+        return data
+    }
+
+    public func write(_ data: Data, to url: URL) throws {
+        if let error = writeError { throw error }
+        files[url] = data
+    }
+
+    public func fileExists(at url: URL) -> Bool {
+        files[url] != nil
+    }
+}
+```
+
+### 4. Inject Dependencies with Default Parameters
+
+Production code uses defaults; tests inject mocks.
+
+```swift
+public actor SyncManager {
+    private let fileSystem: FileSystemProviding
+    private let fileAccessor: FileAccessorProviding
+
+    public init(
+        fileSystem: FileSystemProviding = DefaultFileSystemProvider(),
+        fileAccessor: FileAccessorProviding = DefaultFileAccessor()
+    ) {
+        self.fileSystem = fileSystem
+        self.fileAccessor = fileAccessor
+    }
+
+    public func sync() async throws {
+        guard let containerURL = fileSystem.containerURL(for: .sync) else {
+            throw SyncError.containerNotAvailable
+        }
+        let data = try fileAccessor.read(
+            from: containerURL.appendingPathComponent("data.json")
+        )
+        // Process data...
+    }
+}
+```
+
+### 5. Write Tests with Swift Testing
+
+```swift
+import Testing
+
+@Test("Sync manager handles missing container")
+func testMissingContainer() async {
+    let mockFileSystem = MockFileSystemProvider(containerURL: nil)
+    let manager = SyncManager(fileSystem: mockFileSystem)
+
+    await #expect(throws: SyncError.containerNotAvailable) {
+        try await manager.sync()
+    }
+}
+
+@Test("Sync manager reads data correctly")
+func testReadData() async throws {
+    let mockFileAccessor = MockFileAccessor()
+    mockFileAccessor.files[testURL] = testData
+
+    let manager = SyncManager(fileAccessor: mockFileAccessor)
+    let result = try await manager.loadData()
+
+    #expect(result == expectedData)
+}
+
+@Test("Sync manager handles read errors gracefully")
+func testReadError() async {
+    let mockFileAccessor = MockFileAccessor()
+    mockFileAccessor.readError = CocoaError(.fileReadCorruptFile)
+
+    let manager = SyncManager(fileAccessor: mockFileAccessor)
+
+    await #expect(throws: SyncError.self) {
+        try await manager.sync()
+    }
+}
+```
+
+## Best Practices
+
+- **Single Responsibility**: Each protocol should handle one concern — don't create "god protocols" with many methods
+- **Sendable conformance**: Required when protocols are used across actor boundaries
+- **Default parameters**: Let production code use real implementations by default; only tests need to specify mocks
+- **Error simulation**: Design mocks with configurable error properties for testing failure paths
+- **Only mock boundaries**: Mock external dependencies (file system, network, APIs), not internal types
+
+## Anti-Patterns to Avoid
+
+- Creating a single large protocol that covers all external access
+- Mocking internal types that have no external dependencies
+- Using `#if DEBUG` conditionals instead of proper dependency injection
+- Forgetting `Sendable` conformance when used with actors
+- Over-engineering: if a type has no external dependencies, it doesn't need a protocol
+
+## When to Use
+
+- Any Swift code that touches file system, network, or external APIs
+- Testing error handling paths that are hard to trigger in real environments
+- Building modules that need to work in app, test, and SwiftUI preview contexts
+- Apps using Swift concurrency (actors, structured concurrency) that need testable architecture