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

race-

mem-

dead-

async-

io-

mut-

exhaust-

objc-

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