@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/debugging-instruments/SKILL.md

@@ -1,454 +1,401 @@
 ---
 name: debugging-instruments
-description: "Debug iOS apps and profile performance using LLDB, Memory Graph Debugger, and Instruments. Use when diagnosing crashes, memory leaks, retain cycles, main thread hangs, slow rendering, build failures, or when profiling CPU, memory, energy, and network usage."
+description: "Xcode debugging and profiling: LLDB, Memory Graph Debugger, Instruments, crashes, leaks and retain cycles, main-thread hangs, slow rendering, build failures, CPU, memory, energy and network profiling. Use when debugging or profiling an iOS app."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Debugging and Instruments
 
-Diagnose crashes, memory leaks, retain cycles, main thread hangs, and performance bottlenecks in iOS apps using LLDB, Memory Graph Debugger, and Instruments. Covers breakpoint workflows, memory graph analysis, hang detection, build failure triage, and Instruments profiling for CPU, memory, energy, and network.
+Baseline: Xcode 26 with iOS 26 devices and simulators. The LLDB commands and
+most Instruments templates are much older and work the same on earlier
+releases.
 
-## Contents
+Covers: LLDB breakpoints, expressions and watchpoints, Malloc Stack Logging,
+Instruments templates, `xctrace`, signposts, and build failures from the
+compiler, SwiftPM or the linker.
 
-- [LLDB Debugging](#lldb-debugging)
-- [Memory Debugging](#memory-debugging)
-- [Hang Diagnostics](#hang-diagnostics)
-- [Build Failure Triage](#build-failure-triage)
-- [Instruments Overview](#instruments-overview)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Hand these to their own skills and keep the answer here to a short pointer:
 
-## LLDB Debugging
+| Topic | Skill |
+|-------|-------|
+| Rewriting SwiftUI views once a trace shows the cost | `swiftui-performance` |
+| `MXMetricManager` subscribers, `MXDiagnosticPayload`, `MXHangDiagnostic` | `metrickit-diagnostics` |
+| Organising benchmarks and perf tests in a test suite | `swift-testing` |
 
-### Essential Commands
+Deeper material: [full LLDB notes](references/lldb-patterns.md) and a
+[template-by-template Instruments guide](references/instruments-guide.md).
 
-```text
-(lldb) po myObject              # Print object description (calls debugDescription)
-(lldb) p myInt                  # Print with type info (uses LLDB formatter)
-(lldb) v myLocal                # Frame variable  -  fast, no code execution
-(lldb) bt                       # Backtrace current thread
-(lldb) bt all                   # Backtrace all threads
-(lldb) frame select 3           # Jump to frame #3 in the backtrace
-(lldb) thread list              # List all threads and their states
-(lldb) thread select 4          # Switch to thread #4
-```
+## LLDB
 
-Use `v` over `po` when you only need a local variable value  -  it does not
-execute code and cannot trigger side effects.
+### Everyday commands
 
-### Breakpoint Management
+| Command | Effect |
+|---------|--------|
+| `v total` | Reads a frame variable straight from memory. Fast, runs no code. |
+| `p total` | Evaluates an expression and prints it with type info through the LLDB formatter. |
+| `po order` | Evaluates an expression and prints the object description (`debugDescription`). |
+| `bt` / `bt all` | Backtrace of the current thread / of every thread. |
+| `frame select 3` | Moves to frame 3 of the backtrace. |
+| `thread list` / `thread select 2` | Lists threads with their state / switches to thread 2. |
+
+Reach for `v` first when all you need is a local value. It executes nothing in
+the target process, so it cannot trigger getters, locks or other side effects.
+
+### Breakpoints
 
 ```text
-(lldb) br set -f ViewModel.swift -l 42          # Break at file:line
-(lldb) br set -n viewDidLoad                     # Break on function name
-(lldb) br set -S setValue:forKey:                 # Break on ObjC selector
-(lldb) br modify 1 -c "count > 10"              # Add condition to breakpoint 1
-(lldb) br modify 1 --auto-continue true          # Log and continue (logpoint)
-(lldb) br command add 1                          # Attach commands to breakpoint
-> po self.title
+(lldb) br set -f CartView.swift -l 88          # file and line
+(lldb) br set -n applicationDidBecomeActive    # function name
+(lldb) br set -S setObject:forKey:             # Objective-C selector
+(lldb) br modify 1 -c "lineItems.count > 20"   # add a condition
+(lldb) br modify -G true 1                     # print, then carry on
+(lldb) br command add 1
+> po lineItems.count
 > continue
 > DONE
-(lldb) br disable 1                              # Disable without deleting
-(lldb) br delete 1                               # Remove breakpoint
+(lldb) br disable 1                            # keep it, but inactive
+(lldb) br delete 1                             # remove it
 ```
 
-### Expression Evaluation
+A breakpoint with commands plus `--auto-continue true` behaves as a logpoint.
+
+### Evaluating and changing state
 
 ```text
-(lldb) expr myArray.count                        # Evaluate Swift expression
-(lldb) e -l swift -- import UIKit                # Import framework in LLDB
-(lldb) e -l swift -- self.view.backgroundColor = .red  # Modify state at runtime
-(lldb) e -l objc -- (void)[CATransaction flush]  # Force UI update after changes
+(lldb) expr lineItems.count
+(lldb) expression -l swift -- import UIKit
+(lldb) expression -l swift -- self.checkoutButton.isEnabled = false
+(lldb) expression -l objc -- (void)[CATransaction flush]
 ```
 
-After modifying a view property in the debugger, call `CATransaction.flush()`
-to see the change immediately without resuming execution.
+The process is paused, so UIKit will not redraw on its own. After changing a
+view property from the debugger, flush the pending `CATransaction` to see the
+change on screen without resuming.
 
 ### Watchpoints
 
 ```text
-(lldb) w set v self.score                        # Break when score changes
-(lldb) w set v self.score -w read               # Break when score is read
-(lldb) w modify 1 -c "self.score > 100"         # Conditional watchpoint
-(lldb) w list                                    # Show active watchpoints
-(lldb) w delete 1                                # Remove watchpoint
+(lldb) w set v self.balance                    # stop on write
+(lldb) w set v self.balance -w read            # stop on read
+(lldb) watchpoint modify -c "self.balance < 0" 1   # only when it goes negative
+(lldb) w list
+(lldb) w delete 1
 ```
 
-Watchpoints are hardware-backed (limited to ~4 on ARM). Use them to find
-unexpected mutations  -  the debugger stops at the exact line that changes
-the value.
+Watchpoints use hardware debug registers, so only about four can be active at
+once on ARM. They answer "who changed this value?": the debugger stops on the
+exact line that performed the write.
 
-### Symbolic Breakpoints
+### Symbolic breakpoints
 
-Set breakpoints on methods without knowing the file. Useful for framework
-or system code:
+A symbolic breakpoint names a symbol rather than a file, which is how you stop
+inside framework or system code whose source you do not have.
 
 ```text
-(lldb) br set -n "UIViewController.viewDidLoad"
-(lldb) br set -r ".*networkError.*"              # Regex on symbol name
-(lldb) br set -n malloc_error_break              # Catch malloc corruption
-(lldb) br set -n UIViewAlertForUnsatisfiableConstraints  # Auto Layout issues
+(lldb) br set -n "UIViewController.viewWillAppear"
+(lldb) br set -r ".*paymentFailed.*"           # regex over symbol names
+(lldb) br set -n malloc_error_break            # heap corruption
+(lldb) breakpoint set --name UIViewAlertForUnsatisfiableConstraints
 ```
 
-In Xcode, use the Breakpoint Navigator (+) to add symbolic breakpoints for
-common diagnostics like `-[UIApplication main]` or `swift_willThrow`.
+In Xcode, open the Breakpoint Navigator, press +, choose Symbolic Breakpoint
+and enter a symbol such as `swift_willThrow` or `-[UIView layoutSubviews]`.
 
-## Memory Debugging
+## Memory
 
-### Memory Graph Debugger Workflow
+### Memory Graph Debugger
 
-1. Run the app in Debug configuration.
-2. Reproduce the suspected leak (navigate to a screen, then back).
-3. Tap the **Memory Graph** button in Xcode's debug bar.
-4. Look for purple warning icons  -  these indicate leaked objects.
-5. Select a leaked object to see its reference graph and backtrace.
+1. Run the Debug configuration.
+2. Reproduce the suspected leak, for example open a screen and close it again.
+3. Click the Memory Graph button in the debug bar.
+4. Objects flagged with a purple warning icon are leaks.
+5. Select one to see what references it and, with stack logging on, where it
+   was allocated.
 
-Enable **Malloc Stack Logging** (Scheme > Diagnostics) before running so
-the Memory Graph shows allocation backtraces.
+Turn on Malloc Stack Logging (Scheme > Run > Diagnostics) before launching;
+without it the graph shows ownership but no allocation backtrace.
 
-### Common Retain Cycle Patterns
-
-**Closure capturing self strongly:**
+### Retain cycles that come up again and again
 
 ```swift
-// LEAK  -  closure holds strong reference to self
-class ProfileViewModel {
-    var onUpdate: (() -> Void)?
-
-    func startObserving() {
-        onUpdate = {
-            self.refresh()  // strong capture of self
+@MainActor
+final class UploadMonitor {
+    var onProgress: ((Double) -> Void)?
+    private var ticker: Timer?
+    private(set) var fraction = 0.0
+
+    func attach() {
+        onProgress = { [weak self] value in
+            self?.fraction = value
         }
     }
-}
 
-// FIXED  -  use [weak self]
-func startObserving() {
-    onUpdate = { [weak self] in
-        self?.refresh()
+    func start() {
+        ticker = Timer.scheduledTimer(withTimeInterval: 2, repeats: true) { [weak self] _ in
+            MainActor.assumeIsolated { self?.poll() }
+        }
     }
-}
-```
-
-**Strong delegate reference:**
 
-```swift
-// LEAK  -  strong delegate creates a cycle
-protocol DataDelegate: AnyObject {
-    func didUpdate()
+    private func poll() {}
 }
 
-class DataManager {
-    var delegate: DataDelegate?  // should be weak
+protocol UploadQueueDelegate: AnyObject {
+    func queueDidDrain(_ queue: UploadQueue)
 }
 
-// FIXED  -  weak delegate
-class DataManager {
-    weak var delegate: DataDelegate?
+final class UploadQueue {
+    weak var delegate: UploadQueueDelegate?
 }
 ```
 
-**Timer retaining target:**
-
-```swift
-// LEAK  -  Timer.scheduledTimer retains its target
-timer = Timer.scheduledTimer(
-    timeInterval: 1.0, target: self,
-    selector: #selector(tick), userInfo: nil, repeats: true
-)
-
-// FIXED  -  use closure-based API with [weak self]
-timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
-    self?.tick()
-}
-```
-
-### Instruments: Allocations and Leaks
-
-- **Allocations template**: Track memory growth over time. Use the
-  "Mark Generation" feature to isolate allocations created between
-  user actions (e.g., open/close a screen).
-- **Leaks template**: Detects leaked allocations, including isolated retain
-  cycles the process can no longer reach. Run alongside Allocations for a
-  complete picture.
-- Filter by your app's module name to exclude system allocations.
-
-For leak or memory-growth triage, pair the tools: use Allocations **Mark
-Generation** before and after the reproduction step to prove retained growth,
-then use Memory Graph Debugger to inspect object ownership and Malloc Stack
-Logging to recover allocation call stacks.
+- A stored closure that captures `self` strongly keeps its owner alive. Capture
+  `[weak self]` and call through `self?`.
+- A strong delegate reference closes a loop. Constrain the protocol to
+  `AnyObject` and store the property as `weak var`.
+- `Timer.scheduledTimer(timeInterval:target:selector:userInfo:repeats:)`
+  retains its target. Use the block API, `scheduledTimer(withTimeInterval:repeats:)`,
+  with `[weak self]`, and invalidate it when done. The block is `@Sendable`, so
+  on a main-actor class it reaches `self` through `MainActor.assumeIsolated`; a
+  timer scheduled from the main thread fires on the main run loop.
+
+### Allocations and Leaks
+
+- **Allocations** shows memory over time and object lifetimes. Use Mark
+  Generation before and after an action (open and close a screen) to isolate
+  what that action left behind.
+- **Leaks** finds allocations nothing points to any more, including cycles that
+  have become unreachable. Record it alongside Allocations for the full picture.
+- Filter the detail view by your module name to hide system allocations.
+
+Triage recipe for a leak or steady growth: mark a generation before and after
+the repro to prove memory is retained, open the Memory Graph Debugger to see
+who owns it, and keep Malloc Stack Logging on for the allocation call stacks.
 
 ### Malloc Stack Logging
 
-Enable in Scheme > Run > Diagnostics > Malloc Stack Logging. This records
-allocation backtraces so the Memory Graph Debugger, Allocations instrument,
-and exported `.memgraph` files can show where objects were created.
+In the scheme editor, open Run, then the Diagnostics tab, and tick Malloc
+Stack Logging. The recorded
+allocation backtraces feed the Memory Graph Debugger, the Allocations
+instrument and exported `.memgraph` files. Export a graph from Xcode (File >
+Export Memory Graph) or Instruments and inspect it from Terminal:
 
 ```bash
-# Inspect an exported memory graph from Xcode or Instruments
-leaks MyApp.memgraph
+leaks Checkout.memgraph
 ```
 
-## Hang Diagnostics
+## Hangs
+
+### Thresholds and detection
 
-### Identifying Main Thread Hangs
+For a discrete interaction such as a tap, a delay below roughly 100 ms goes
+unnoticed, while a few hundred milliseconds already makes the app feel stuck.
+Apple's tools usually start reporting once the main run loop stays busy for
+more than 250 ms. Keep those two numbers apart: the tool threshold is not the
+point where users start to notice.
 
-For discrete interactions, delays under 100 ms are rarely noticeable; a few
-hundred milliseconds can make an app feel unresponsive. Apple developer tools
-typically start reporting main-run-loop busy periods over 250 ms. Common
-detection tools:
+Tools, from development to production:
 
-- **Thread Checker** (Xcode Diagnostics): warns about non-main-thread UI calls
-- **Thread Performance Checker**: reports priority inversions while debugging
-- **On-device Hang Detection**: Developer Settings reports hangs from device use
-- **Time Profiler / CPU Profiler / Hitches**: profile reproducible hangs
-- **os_signpost** and `OSSignposter`: mark intervals for Instruments
-- **MetricKit** hang diagnostics: production hang detection (see
-  `metrickit` skill for `MXHangDiagnostic`)
+- Thread Checker (Scheme > Diagnostics) flags UI calls made off the main thread.
+- Thread Performance Checker flags priority inversions during a debug session.
+- Hang Detection under Developer settings on the device reports hangs as you
+  use the app.
+- Time Profiler, CPU Profiler and Hitches profile a hang you can reproduce.
+- `os_signpost` and `OSSignposter` put your own intervals on the Instruments
+  timeline.
+- MetricKit's `MXHangDiagnostic` catches hangs in the field; see
+  `metrickit-diagnostics`.
 
 ```swift
 import os
 
-let signposter = OSSignposter(subsystem: "com.example.app", category: "DataLoad")
+let tripSignposts = OSSignposter(subsystem: "app.atlas.trips", category: "Sync")
 
-func loadData() async {
-    let state = signposter.beginInterval("loadData")
-    let result = await fetchFromNetwork()
-    signposter.endInterval("loadData", state)
-    process(result)
+func refreshTrips(from client: TripClient, into store: TripStore) async throws {
+    let state = tripSignposts.beginInterval("fetchTrips")
+    let trips = try await client.trips()
+    tripSignposts.endInterval("fetchTrips", state)
+    store.merge(trips)
 }
 ```
 
-### Using the Time Profiler
+### Time Profiler in five steps
 
-1. Product > Profile (Cmd+I) to launch Instruments.
-2. Select the **Time Profiler** template.
-3. Record while reproducing the slow interaction.
-4. Focus on the main thread  -  sort by "Weight" to find hot paths.
-5. Check "Hide System Libraries" to see only your code.
-6. Double-click a heavy frame to jump to source.
+1. Product > Profile (Cmd+I).
+2. Pick Time Profiler, start recording, then perform the sluggish action.
+3. Look at the main thread and sort by Weight to find the hot path.
+4. Turn on Hide System Libraries to keep only your code.
+5. Double-click an expensive frame to open the matching source line.
 
-### Common Hang Causes
+### Usual causes
 
 | Cause | Symptom | Fix |
 |-------|---------|-----|
-| Synchronous I/O on main thread | Network/file reads block UI | Move to `Task { }` or background actor |
-| Lock contention | Main thread waiting on a lock held by background work | Use actors or reduce lock scope |
-| Layout thrashing | Repeated `layoutSubviews` calls | Batch layout changes, avoid forced layout |
-| JSON parsing large payloads | UI freezes during data load | Parse on a background thread |
-| Synchronous image decoding | Scroll jank on image-heavy lists | Use `AsyncImage` or decode off main thread |
+| Synchronous file or network I/O on main | UI freezes while data loads | Do the work in a `Task` or a background actor |
+| Lock contention | Main waits on a lock a background job holds | Use an actor or shrink the critical section |
+| Layout thrash | `layoutSubviews` runs over and over | Batch layout changes, avoid forcing layout |
+| Large JSON decode on main | Screen stalls during load | Decode off the main thread |
+| Synchronous image decoding | Jank while scrolling an image list | `AsyncImage`, or decode and downsample off main |
 
-## Build Failure Triage
+## Build Failures
 
-### Reading Compiler Diagnostics
+### Compiler diagnostics
 
-- Start from the **first** error  -  subsequent errors are often cascading.
-- Search for the error code (e.g., `error: cannot convert`) in the build log.
-- Use Report Navigator (Cmd+9) for the full build log with timestamps.
+Fix the first error first; many later errors cascade from it. Search the log
+for the message text (for example `error: cannot convert`). The Report
+Navigator (Cmd+9) keeps the full, timestamped build log.
 
-### SPM Dependency Resolution
+### SwiftPM resolution
 
-```text
-# Common: version conflict
-error: Dependencies could not be resolved because root depends on 'Package' 1.0.0..<2.0.0
+When versions clash, resolution fails and the message names the requirement
+that cannot be met, typically a range such as `1.0.0..<2.0.0` on one package.
+Read `Package.resolved`, then loosen or align the version requirements. When
+the cache itself is suspect:
 
-# Fix: check Package.resolved and update version ranges
-# Reset package caches if needed:
-rm -rf ~/Library/Caches/org.swift.swiftpm
+```bash
 rm -rf .build
+rm -rf "$HOME/Library/Caches/org.swift.swiftpm"
 swift package resolve
 ```
 
-### Module Not Found / Linker Errors
+### Missing modules and linker errors
 
-| Error | Check |
-|-------|-------|
-| `No such module 'Foo'` | Target membership, import paths, framework search paths |
-| `Undefined symbol` | Linking phase missing framework, wrong architecture |
-| `duplicate symbol` | Two targets define same symbol; check for ObjC naming collisions |
+| Message | Look at |
+|---------|---------|
+| `No such module 'Foo'` | Is the file in the right target? Then the import and framework search paths |
+| `Undefined symbol` | A framework missing from the link phase, or the wrong architecture |
+| `duplicate symbol` | Two targets defining one symbol; Objective-C name clashes |
 
-Build settings to inspect first:
-- `FRAMEWORK_SEARCH_PATHS`
-- `OTHER_LDFLAGS`
-- `SWIFT_INCLUDE_PATHS`
-- `BUILD_LIBRARY_FOR_DISTRIBUTION` (for XCFrameworks)
+Check these build settings first: `FRAMEWORK_SEARCH_PATHS`, `OTHER_LDFLAGS`,
+`SWIFT_INCLUDE_PATHS`, and `BUILD_LIBRARY_FOR_DISTRIBUTION` for XCFrameworks.
 
-## Instruments Overview
+## Instruments
 
-### Template Selection Guide
+### Picking a template
 
-| Template | Use When |
+| Question | Template |
 |----------|----------|
-| **Time Profiler** | CPU is high, UI feels slow, need to find hot code paths |
-| **Allocations** | Memory grows over time, need to track object lifetimes |
-| **Leaks** | Suspect retain cycles or abandoned objects |
-| **Network** | Inspecting HTTP request/response timing and payloads |
-| **SwiftUI** | Profiling view body evaluations and update frequency |
-| **Animation Hitches / Core Animation instruments** | Frame drops, hitches, blending, and commit/render work |
-| **Power Profiler** | Battery drain, thermal pressure, background energy impact |
-| **File Activity** | Excessive disk I/O, slow file operations |
-| **System Trace** | Thread scheduling, syscalls, virtual memory faults |
-
-### xctrace CLI for CI Profiling
+| High CPU, slow UI, where is the time going? | Time Profiler |
+| Memory growth, object lifetimes | Allocations |
+| Suspected retain cycles or abandoned objects | Leaks |
+| Request timing and payloads | Network |
+| How often SwiftUI bodies run and why | SwiftUI |
+| Dropped frames, blending, commit and render cost | Animation Hitches, Core Animation instruments |
+| Battery drain, heat, background energy | Power Profiler |
+| Heavy or slow disk access | File Activity |
+| Scheduling, system calls, VM faults | System Trace |
+
+### xctrace on the command line and in CI
 
 ```bash
-# Record a trace from the command line
-xcrun xctrace record --device "My iPhone" \
-    --template "Time Profiler" \
-    --instrument "Allocations" \
-    --output profile.trace \
-    --launch -- /path/to/MyApp.app
-
-# Export trace data as XML for automated analysis
-xcrun xctrace export --input profile.trace --xpath '/trace-toc/run/data/table'
-
-# List available templates
+xcrun xctrace record --device "QA iPhone" \
+  --template "Time Profiler" --instrument "Allocations" \
+  --output launch.trace --launch -- /path/to/Atlas.app
+xcrun xctrace export --input launch.trace --xpath '/trace-toc/run/data/table'
 xcrun xctrace list templates
-
-# List connected devices
 xcrun xctrace list devices
 ```
 
-Use one `--template` per recording; add extra instruments with
-`--instrument`. Use `xctrace` in CI pipelines to catch performance regressions
-automatically. Compare exported metrics between builds.
+A recording takes exactly one `--template`; add further instruments with
+`--instrument`. Everything after `--launch --` is the app and its arguments.
+Run the same recording in CI and compare the exported tables between builds to
+catch regressions.
 
 ## Common Mistakes
 
-### DON'T: Use print() for debugging instead of os.Logger
+### `print()` instead of `Logger`
 
-`print()` output is unstructured, has no subsystem/category or privacy
-metadata, and is harder to filter than unified logging.
+Output from `print()` carries no subsystem, category or privacy annotation, so
+nobody can filter it later. Use unified logging:
 
 ```swift
-// WRONG  -  unstructured and not filterable by subsystem/category
-print("user tapped button, state: \(viewModel.state)")
-print("network response: \(data)")
-
-// CORRECT  -  structured logging with Logger
 import os
 
-let logger = Logger(subsystem: "com.example.app", category: "UI")
-
-logger.debug("Button tapped, state: \(viewModel.state, privacy: .public)")
-logger.info("Network response received, bytes: \(data.count)")
-```
-
-`Logger` messages appear in Console.app with filtering by subsystem and
-category, and `.debug` messages are written to the in-memory log store only (not persisted to disk in release builds).
-
-### DON'T: Forget to enable Malloc Stack Logging before memory debugging
+let log = Logger(subsystem: "app.atlas.checkout", category: "Orders")
 
-Without Malloc Stack Logging, the Memory Graph Debugger shows leaked
-objects but cannot display allocation backtraces, making it difficult to
-find the code that created them.
-
-```swift
-// WRONG  -  open Memory Graph without enabling Malloc Stack Logging
-// Result: leaked objects visible but no allocation backtrace
-
-// CORRECT  -  enable BEFORE running:
-// Scheme > Run > Diagnostics > check "Malloc Stack Logging: All Allocations"
-// Then run, reproduce the leak, and open Memory Graph
+func submit(order id: String, items: Int) {
+    log.debug("Submitting \(id, privacy: .public) with \(items) items")
+    log.info("Order submitted")
+}
 ```
 
-### DON'T: Debug optimized code expecting full variable visibility
+Console.app filters by subsystem and category. By default `.debug` messages
+stay in the in-memory log store and are not persisted to disk.
 
-In Release (optimized) builds, the compiler may inline functions, eliminate
-variables, and reorder code. LLDB cannot display optimized-away values.
+### Memory Graph without Malloc Stack Logging
 
-```swift
-// WRONG  -  profiling with Debug build, debugging with Release build
-// Debug builds: extra runtime checks distort perf measurements
-// Release builds: variables show as "<optimized out>" in debugger
+The graph still shows leaked objects but not where they were allocated. Before
+launching, choose All Allocations for Malloc Stack Logging in the scheme's
+Diagnostics tab; then run, reproduce and open the graph.
 
-// CORRECT approach:
-// Debugging: use Debug configuration (full symbols, no optimization)
-// Profiling: use Release configuration (realistic performance)
-```
+### Debugging or profiling the wrong configuration
 
-### DON'T: Stop on every loop iteration without conditional breakpoints
+Optimised Release code inlines, reorders and drops variables, so LLDB prints
+`<optimized out>`. Debug builds add runtime checks that skew timings. Debug
+with the Debug configuration; profile with Release.
 
-Breaking on every iteration wastes time and makes it hard to find the
-specific case you care about.
+### Stopping on every loop iteration
 
-```swift
-// WRONG  -  breakpoint on line inside loop, stops 10,000 times
-for item in items {
-    process(item)  // breakpoint here stops on EVERY item
-}
+Add a condition instead:
+`br set -f OrderList.swift -l 42 -c "row.id == wantedID"`, or right-click the
+breakpoint in Xcode, choose Edit Breakpoint and fill in Condition.
 
-// CORRECT  -  use a conditional breakpoint:
-// (lldb) br set -f MyFile.swift -l 42 -c "item.id == targetID"
-// Or in Xcode: right-click breakpoint > Edit > add Condition
-```
+### Dismissing Thread Sanitizer warnings
 
-### DON'T: Ignore Thread Sanitizer warnings
-
-Thread Sanitizer (TSan) warnings indicate data races that may only crash
-intermittently. Treat them as real bugs unless you have isolated a tool issue.
+A TSan report is a real data race that may crash only now and then. Treat it as
+a bug until you can show the tool itself is wrong. Protect the shared state,
+for example with an actor:
 
 ```swift
-// WRONG  -  ignoring TSan warning about concurrent access
-var cache: [String: Data] = [:]  // accessed from multiple threads
+actor ThumbnailCache {
+    private var images: [URL: Data] = [:]
 
-// CORRECT  -  protect shared mutable state
-actor CacheActor {
-    var cache: [String: Data] = [:]
+    func image(for url: URL) -> Data? { images[url] }
 
-    func get(_ key: String) -> Data? { cache[key] }
-    func set(_ key: String, _ value: Data) { cache[key] = value }
+    func store(_ data: Data, for url: URL) { images[url] = data }
 }
 ```
 
-Enable TSan: Scheme > Run > Diagnostics > Thread Sanitizer. For iOS, iPadOS,
-tvOS, visionOS, and watchOS apps, run TSan in Simulator; Apple documents device
-support only for 64-bit macOS apps.
-
-### Correction Pattern: Flawed Memory and Hang Plans
+Turn it on in the scheme's Diagnostics tab. Apps for iOS, iPadOS, tvOS,
+visionOS and watchOS get it in Simulator; the only devices Apple lists as
+supported are Macs running 64-bit macOS apps.
 
-When correcting another diagnostic plan, explicitly check these points:
+### Correcting a flawed memory or hang plan
 
-- **Leaks scope**: Leaks can catch unreachable abandoned allocations and
-  isolated retain cycles the process can no longer reach; it does not prove
-  every retain cycle still reachable from roots.
-- **Memory growth**: Use Allocations **Mark Generation** before and after the
-  reproduction step, then use Memory Graph Debugger for ownership and Malloc
-  Stack Logging for allocation backtraces.
-- **Hang severity**: Distinguish tool reporting from severity. Developer tools
-  commonly report main-run-loop busy periods over 250 ms, while a few hundred
-  milliseconds can still feel unresponsive to users.
+- Leaks catches abandoned, unreachable allocations and isolated unreachable
+  cycles. It does not prove that every cycle still reachable from a root is
+  gone; use the Memory Graph and Allocations generations for those.
+- For growth: generations around the repro, the Memory Graph to see who holds
+  the memory, and stack logging to see where it came from.
+- For severity: tools report above 250 ms, but users can feel a few hundred
+  milliseconds. Do not treat "under the tool threshold" as "fine".
 
 ## Review Checklist
 
-- [ ] Using `os.Logger` instead of `print()` for diagnostic output
-- [ ] Malloc Stack Logging enabled before memory debugging sessions
-- [ ] Memory Graph Debugger checked after dismiss/dealloc flows
-- [ ] Delegates declared as `weak var` to prevent retain cycles
-- [ ] Closures stored as properties use `[weak self]` capture lists
-- [ ] Timers use closure-based API with `[weak self]`
-- [ ] Thread Sanitizer enabled in Simulator test schemes for race triage
-- [ ] No synchronous I/O or heavy computation on the main thread
-- [ ] Time Profiler run on Release build for performance baselines
-- [ ] Build failures triaged from the first error in the build log
-- [ ] `OSSignposter` used for custom performance intervals
-- [ ] Conditional breakpoints used for loop/collection debugging
-
-## References
-
-- [Logging (unified logging system)](https://sosumi.ai/documentation/os/logging)
-- [Logger](https://sosumi.ai/documentation/os/logger)
-- [OSSignposter](https://sosumi.ai/documentation/os/ossignposter)
-- [Generating log messages from your code](https://sosumi.ai/documentation/os/generating-log-messages-from-your-code)
-- [Recording performance data (signposts)](https://sosumi.ai/documentation/os/recording-performance-data)
-- [Diagnosing memory, thread, and crash issues early](https://sosumi.ai/documentation/xcode/diagnosing-memory-thread-and-crash-issues-early)
-- [Data races](https://sosumi.ai/documentation/xcode/data-races)
-- [Reducing your app's memory use](https://sosumi.ai/documentation/xcode/reducing-your-app-s-memory-use)
-- [Profiling apps using Instruments](https://developer.apple.com/tutorials/instruments)
-- [Improving app responsiveness](https://sosumi.ai/documentation/xcode/improving-app-responsiveness)
-- [Analyzing your app's battery use](https://sosumi.ai/documentation/xcode/analyzing-your-app-s-battery-use)
-- [Analyzing the performance of your shipping app](https://sosumi.ai/documentation/xcode/analyzing-the-performance-of-your-shipping-app)
-- LLDB command reference: [references/lldb-patterns.md](references/lldb-patterns.md)
-- Instruments template guide: [references/instruments-guide.md](references/instruments-guide.md)
+- [ ] `os.Logger` instead of `print()`
+- [ ] Malloc Stack Logging on before memory sessions
+- [ ] Memory Graph checked after dismiss and deallocation flows
+- [ ] Delegates declared `weak var`
+- [ ] Stored closures capture `[weak self]`
+- [ ] Timers use the block API with `[weak self]`
+- [ ] Thread Sanitizer on in Simulator test schemes when chasing races
+- [ ] Main thread free of blocking I/O and long computations
+- [ ] Time Profiler baselines recorded from Release builds
+- [ ] Failed builds read from the earliest error down
+- [ ] `OSSignposter` intervals around custom performance-critical work
+- [ ] Conditional breakpoints for loops and collections
+
+## Apple Documentation
+
+- [Logging](https://developer.apple.com/documentation/os/logging)
+- [Logger](https://developer.apple.com/documentation/os/logger)
+- [OSSignposter](https://developer.apple.com/documentation/os/ossignposter)
+- [Writing log messages](https://developer.apple.com/documentation/os/generating-log-messages-from-your-code)
+- [Recording performance data](https://developer.apple.com/documentation/os/recording-performance-data)
+- [Catching memory, threading and crash bugs early](https://developer.apple.com/documentation/xcode/diagnosing-memory-thread-and-crash-issues-early)
+- [Data races](https://developer.apple.com/documentation/xcode/data-races)
+- [Lowering memory use](https://developer.apple.com/documentation/xcode/reducing-your-app-s-memory-use)
+- [Improving app responsiveness](https://developer.apple.com/documentation/xcode/improving-app-responsiveness)
+- [Battery use](https://developer.apple.com/documentation/xcode/analyzing-your-app-s-battery-use)
+- [Performance of a shipped app](https://developer.apple.com/documentation/xcode/analyzing-the-performance-of-your-shipping-app)
+- [Instruments tutorials](https://developer.apple.com/tutorials/instruments)