ios-chaos-monkey

iOS Chaos Monkey — Crash-Hunter Best Practices

Adversarial crash-hunting guide for iOS and Swift applications. Contains 47 rules across 8 categories, prioritized by crash severity. Every rule follows TDD: dangerous code first, a failing test that proves the bug, then the fix that makes the test pass.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Hunting data races, deadlocks, and concurrency crashes in Swift
• Auditing memory management for retain cycles and use-after-free
• Reviewing async/await code for cancellation and continuation leaks
• Stress-testing file I/O and CoreData/SwiftData persistence layers
• Writing proof-of-crash tests before implementing fixes

Rule Categories by Priority

Quick Reference

1. Data Races & Thread Safety (CRITICAL)

• race-dictionary-concurrent-write - Concurrent Dictionary mutation crashes with EXC_BAD_ACCESS
• race-array-concurrent-append - Concurrent Array append corrupts internal buffer
• race-property-access - Unsynchronized property read-write across threads
• race-lazy-initialization - Lazy property double-initialization under concurrency
• race-singleton-initialization - Non-atomic singleton exposes partially constructed state
• race-bool-flag - Non-atomic Bool flag creates check-then-act race
• race-closure-capture-mutation - Closure captures mutable reference across threads
• race-delegate-nilification - Delegate set to nil during active callback

2. Memory Corruption & Leaks (CRITICAL)

• mem-closure-retain-cycle - Strong self capture in escaping closures creates retain cycle
• mem-timer-retain-cycle - Timer retains target creating undiscoverable retain cycle
• mem-delegate-strong-reference - Strong delegate reference prevents deallocation
• mem-unowned-crash - Unowned reference crashes after owner deallocation
• mem-notification-observer-leak - NotificationCenter observer retains closure after removal needed
• mem-combine-sink-retain - Combine sink retains self without cancellable storage
• mem-async-task-self-capture - Task captures self extending lifetime beyond expected scope

3. Deadlocks & Thread Starvation (HIGH)

• dead-sync-on-main - DispatchQueue.main.sync from main thread deadlocks instantly
• dead-recursive-lock - Recursive lock acquisition on same serial queue
• dead-actor-reentrancy - Actor reentrancy produces unexpected interleaving
• dead-semaphore-in-async - Semaphore.wait() inside async context deadlocks thread pool
• dead-queue-hierarchy - Dispatch queue target hierarchy inversion deadlocks
• dead-mainactor-blocking - Blocking MainActor with synchronous heavy work

4. Async/Await & Structured Concurrency (HIGH)

• async-missing-cancellation - Missing Task.isCancelled check wastes resources after navigation
• async-detached-task-leak - Detached task without cancellation handle leaks work
• async-task-group-error - TaskGroup silently drops child task errors
• async-continuation-leak - CheckedContinuation never resumed leaks awaiting task
• async-actor-hop-starvation - Excessive MainActor hops in hot loop starve UI updates
• async-unsafe-sendable - @unchecked Sendable hides data race from compiler

5. File I/O & Persistence Corruption (MEDIUM-HIGH)

• io-concurrent-file-write - Concurrent file writes corrupt data without coordination
• io-coredata-cross-thread - CoreData NSManagedObject accessed from wrong thread
• io-swiftdata-background - SwiftData model accessed from wrong ModelContext
• io-plist-concurrent-mutation - UserDefaults concurrent read-write produces stale values
• io-filemanager-race - FileManager existence check then use is a TOCTOU race
• io-keychain-thread-safety - Keychain access from multiple threads returns unexpected errors

6. Collection & State Mutation (MEDIUM)

• mut-enumerate-and-mutate - Collection mutation during enumeration crashes at runtime
• mut-kvo-dealloc-crash - KVO observer not removed before deallocation crashes
• mut-index-out-of-bounds - Array index access without bounds check crashes
• mut-force-unwrap - Force unwrapping optional in production crashes on nil
• mut-enum-future-cases - Non-exhaustive switch crashes on unknown enum case

7. Resource Exhaustion (MEDIUM)

• exhaust-unbounded-task-spawn - Unbounded task spawning in loop exhausts memory
• exhaust-thread-explosion - GCD creates unbounded threads under concurrent load
• exhaust-urlsession-leak - URLSession not invalidated leaks delegate and connections
• exhaust-file-descriptor-leak - File handle not closed leaks file descriptors
• exhaust-memory-warning-ignored - Low memory warning ignored triggers Jetsam kill

8. Objective-C Interop Traps (LOW-MEDIUM)

• objc-unrecognized-selector - Missing @objc annotation crashes with unrecognized selector
• objc-nsnull-in-json - NSNull in decoded JSON collection crashes on access
• objc-bridge-type-mismatch - Swift/ObjC bridge type mismatch crashes at runtime
• objc-dynamic-dispatch - Missing dynamic keyword breaks method swizzling

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files