playbooks

home / skills / pproenca / dot-skills / ios-chaos-monkey

ios-chaos-monkey skill

/skills/.experimental/ios-chaos-monkey

This skill helps you identify and fix iOS concurrency, memory, and I/O crashes with test-driven rules that prove failures and provide fixes.

npx playbooks add skill pproenca/dot-skills --skill ios-chaos-monkey

Review the files below or copy the command above to add this skill to your agents.

Files (51)
SKILL.md
8.4 KB
---
name: ios-chaos-monkey
description: iOS crash-hunter skill that finds and fixes gnarly concurrency, memory, and I/O bugs using TDD. Every rule shows dangerous code, a failing test that proves the crash, and the fix that makes it pass. Complements ios-testing, swift-optimise, and other ios-*/swift-* skills. Triggers on tasks involving data races, retain cycles, deadlocks, async/await pitfalls, file corruption, thread safety, or crash debugging in Swift/iOS apps.
---

# 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.

## 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

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Data Races & Thread Safety | CRITICAL | `race-` |
| 2 | Memory Corruption & Leaks | CRITICAL | `mem-` |
| 3 | Deadlocks & Thread Starvation | HIGH | `dead-` |
| 4 | Async/Await & Structured Concurrency | HIGH | `async-` |
| 5 | File I/O & Persistence Corruption | MEDIUM-HIGH | `io-` |
| 6 | Collection & State Mutation | MEDIUM | `mut-` |
| 7 | Resource Exhaustion | MEDIUM | `exhaust-` |
| 8 | Objective-C Interop Traps | LOW-MEDIUM | `objc-` |

## Quick Reference

### 1. Data Races & Thread Safety (CRITICAL)

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

### 2. Memory Corruption & Leaks (CRITICAL)

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

### 3. Deadlocks & Thread Starvation (HIGH)

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

### 4. Async/Await & Structured Concurrency (HIGH)

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

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

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

### 6. Collection & State Mutation (MEDIUM)

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

### 7. Resource Exhaustion (MEDIUM)

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

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

- [`objc-unrecognized-selector`](references/objc-unrecognized-selector.md) - Missing @objc annotation crashes with unrecognized selector
- [`objc-nsnull-in-json`](references/objc-nsnull-in-json.md) - NSNull in decoded JSON collection crashes on access
- [`objc-bridge-type-mismatch`](references/objc-bridge-type-mismatch.md) - Swift/ObjC bridge type mismatch crashes at runtime
- [`objc-dynamic-dispatch`](references/objc-dynamic-dispatch.md) - Missing dynamic keyword breaks method swizzling

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

Overview

This skill is an adversarial iOS crash-hunter that finds and fixes gnarly concurrency, memory, and I/O bugs using a test-driven approach. Every rule demonstrates the dangerous code, a failing test that reproduces the crash, and the minimal fix that makes the test pass. It complements other iOS/Swift quality skills and triggers on crash-prone tasks in Swift/iOS apps.

How this skill works

The skill inspects source patterns and task descriptions for indicators like data races, retain cycles, deadlocks, async/await pitfalls, and file I/O races. For each matched rule it produces a failing unit test that proves the bug, highlights the offending code, and suggests a tested fix with rationale and minimal changes. Rules are prioritized by crash severity to focus immediate attention on the most dangerous defects.

When to use it

  • During code review when concurrent access, actor misuse, or GCD usage looks suspicious.
  • When triaging crashes that suggest EXC_BAD_ACCESS, deadlocks, or intermittent corruption.
  • While adding or refactoring async/await code to avoid continuation and cancellation leaks.
  • During persistence audits for CoreData, SwiftData, file writes, or UserDefaults races.
  • As part of writing tests: convert heuristic crash reports into reproducible failing tests before fixing.

Best practices

  • Always write a failing unit or integration test that reproduces the crash before applying a fix.
  • Prioritize fixes from critical categories first: data races and memory corruption come before performance tweaks.
  • Prefer minimal, well-scoped changes that make the failing test pass and add safeguards (locks, actors, or atomic patterns).
  • Use structured concurrency and cancellation checks; avoid synchronous waits on async contexts.
  • Document thread-affinity and ownership for APIs that access non-thread-safe resources (CoreData, file handles).

Example use cases

  • Convert an intermittent EXC_BAD_ACCESS from concurrent Array mutation into a failing test and fix it with synchronization.
  • Detect a retain cycle caused by an escaping closure, produce a test that observes the leak, and apply weak captures.
  • Reproduce a deadlock introduced by DispatchQueue.main.sync and change the call to async or restructure the API.
  • Catch a missing Task cancellation check in a long-running operation and add cooperative cancellation with tests.
  • Find concurrent file writes that corrupt a database and propose coordinated writes or file-locking with an integration test.

FAQ

Does the skill automatically modify source files?

It suggests minimal, tested fixes and example patches, but you should review and apply changes within your codebase to ensure design constraints are respected.

Which kinds of crashes does it prioritize?

It prioritizes data races and memory corruption first, then deadlocks and async/await pitfalls, followed by I/O and resource exhaustion issues.