@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/debugging-instruments/references/instruments-guide.md

@@ -0,0 +1,387 @@
+# Instruments Guide Reference
+
+Detailed template-by-template guide for profiling iOS apps with Instruments. Companion to the main `debugging-instruments` skill.
+
+## Contents
+
+- [General Workflow](#general-workflow)
+- [Time Profiler](#time-profiler)
+- [Allocations](#allocations)
+- [Leaks](#leaks)
+- [Network](#network)
+- [SwiftUI Instruments](#swiftui-instruments)
+- [Core Animation](#core-animation)
+- [Energy Log](#energy-log)
+- [File Activity](#file-activity)
+- [System Trace](#system-trace)
+- [xctrace CLI](#xctrace-cli)
+- [Custom Instruments with os_signpost](#custom-instruments-with-os_signpost)
+- [Automation and CI Integration](#automation-and-ci-integration)
+
+## General Workflow
+
+1. **Build for profiling**: Product > Profile (Cmd+I). This builds with Release optimization by default.
+2. **Select a template** from the Instruments chooser.
+3. **Configure recording**: Set the target device and process.
+4. **Record**: Press the red record button and reproduce the scenario.
+5. **Analyze**: Use the timeline, detail views, and call tree to find issues.
+6. **Filter**: Check "Hide System Libraries" and use the search bar to focus on your code.
+
+Always profile on a **physical device** for accurate measurements. Simulator
+performance does not reflect real-world behavior.
+
+## Time Profiler
+
+**When to use**: CPU is high, UI is slow, animations stutter, or you need to
+find which functions consume the most time.
+
+### Key Workflow
+
+1. Record while reproducing the slow interaction.
+2. Select the time range of interest in the timeline.
+3. Switch to the **Call Tree** view in the detail pane.
+4. Enable these checkboxes:
+   - **Separate by Thread** — isolate main thread vs background
+   - **Invert Call Tree** — show leaf functions (actual work) first
+   - **Hide System Libraries** — focus on your code
+5. Sort by **Weight** (self time) to find the hottest functions.
+6. Double-click a function to view source with per-line timing.
+
+### Reading the Call Tree
+
+- **Weight**: total time in this function and all its callees
+- **Self Weight**: time spent in this function alone (not callees)
+- **Symbol Name**: the function — look for your module prefix
+
+Focus on functions with high **Self Weight** — these are doing the actual work.
+
+### Tips
+
+- Profile the same user interaction 3 times to get stable measurements.
+- Use the **Comparison** view to diff traces before/after a fix.
+- Check "Flatten Recursion" if recursive calls make the tree hard to read.
+
+## Allocations
+
+**When to use**: Memory grows over time, you suspect objects are not being
+freed, or you need to track object lifetimes.
+
+### Key Workflow
+
+1. Record while reproducing the scenario.
+2. Use **Mark Generation** (button in the detail pane) to snapshot allocations
+   at specific points. For example:
+   - Mark before navigating to a screen
+   - Navigate to the screen
+   - Navigate back
+   - Mark again
+   - The difference shows objects that were not freed
+3. Expand a generation to see allocations grouped by category.
+4. Filter by your module name to exclude system allocations.
+
+### Allocation Lifespan
+
+- **Created & Still Living**: objects allocated and not yet freed
+- **Created & Destroyed**: objects with normal lifetimes
+- **Persistent**: long-lived allocations (singletons, caches)
+- **Transient**: short-lived allocations (autoreleased, temporary)
+
+Focus on "Created & Still Living" objects in the generation diff — these
+are your potential leaks.
+
+### Heap Growth Analysis
+
+Enable the **Allocations List** and sort by **Persistent Bytes**. Look for:
+- Classes with unexpectedly high instance counts
+- Image data or NSData objects that should have been released
+- View controllers that persist after dismissal
+
+## Leaks
+
+**When to use**: Suspected retain cycles or abandoned memory.
+
+### Key Workflow
+
+1. Run with the Leaks template.
+2. The tool automatically checks for leaks every 10 seconds.
+3. Red "Leak" markers appear in the timeline when leaks are detected.
+4. Click a leak marker to see the leaked object and its retain/release history.
+5. The **Cycles & Roots** view shows the reference graph — follow the arrows
+   to find the cycle.
+
+### Interpreting Results
+
+- **Leak**: an object with no references pointing to it (true orphan)
+- **Root Leak**: the object at the head of a leaked object graph
+- **Cycles & Roots graph**: arrows show retain relationships — look for
+  bidirectional arrows indicating a cycle
+
+### Common Cycle Patterns
+
+Leaks instrument commonly catches:
+- Closure -> self -> closure cycles
+- Delegate strong reference cycles
+- NotificationCenter observer blocks retaining self
+- CADisplayLink/Timer retaining target
+
+## Network
+
+**When to use**: Inspecting HTTP request/response timing, payload sizes,
+or connection reuse.
+
+### Key Workflow
+
+1. Record with the Network template.
+2. Each HTTP request appears as a bar in the timeline.
+3. Select a request to see:
+   - URL, method, status code
+   - Request/response headers
+   - Timing breakdown (DNS, connect, TLS, request, response)
+   - Payload size
+
+### What to Look For
+
+- **Waterfall gaps**: sequential requests that could be parallelized
+- **Large payloads**: responses that could use pagination or compression
+- **Redundant requests**: duplicate calls to the same endpoint
+- **DNS/TLS latency**: consider connection prewarming
+
+## SwiftUI Instruments
+
+**When to use**: SwiftUI view body is evaluated too frequently, unnecessary
+redraws, or identity churn in lists.
+
+### Key Workflow
+
+1. Select the **SwiftUI** template in Instruments.
+2. Record while interacting with the UI.
+3. Check these lanes:
+   - **View Body**: shows each body evaluation with the view type
+   - **View Properties**: tracks property changes that trigger updates
+4. Look for views with excessive body evaluations during a single interaction.
+
+### Tips
+
+- Filter by view name to focus on a specific component.
+- Cross-reference with Time Profiler to see if body evaluations are expensive.
+- See the `swiftui-performance` skill for remediation patterns.
+
+## Core Animation
+
+**When to use**: Frame drops, off-screen rendering, excessive blending.
+
+### Key Workflow
+
+1. Record with the Core Animation template on a real device.
+2. Check the **FPS** lane for drops below 60 (or 120 on ProMotion devices).
+3. Enable these debug options in the Recording Options:
+   - **Color Blended Layers** — red areas have multiple overlapping layers
+   - **Color Off-screen Rendered** — yellow areas use off-screen passes
+   - **Color Hits Green and Misses Red** — rasterization cache hits/misses
+
+### Common Issues
+
+| Issue | Indicator | Fix |
+|-------|-----------|-----|
+| Transparent overlapping views | Red blended layers | Use opaque backgrounds |
+| Corner radius + clip | Off-screen rendering | Use `cornerCurve` with pre-masked images |
+| Shadow without path | Off-screen rendering | Set `shadowPath` explicitly |
+| Large images not downsampled | High memory + slow rendering | Downsample before display |
+
+## Energy Log
+
+**When to use**: Battery drain complaints, background energy impact, or
+App Store rejection for excessive energy use.
+
+### Key Workflow
+
+1. Record with the Energy Log template on a physical device.
+2. Check the **Energy Impact** lane for high/very high readings.
+3. Examine component breakdown:
+   - CPU
+   - Network
+   - Location
+   - GPU
+   - Background tasks
+
+### Tips
+
+- Profile typical user sessions (5-10 minutes of real usage).
+- Compare foreground vs background energy impact.
+- Check that background tasks complete and do not run indefinitely.
+- Cross-reference with MetricKit energy metrics from production.
+
+## File Activity
+
+**When to use**: Slow file operations, excessive disk I/O, or disk write
+exceptions from MetricKit.
+
+### Key Workflow
+
+1. Record with the File Activity template.
+2. Look for:
+   - Frequent writes to the same file (journaling, logging)
+   - Large reads on the main thread
+   - Unintended file access patterns
+
+## System Trace
+
+**When to use**: Deep investigation of thread scheduling, virtual memory
+faults, system calls, and inter-process communication.
+
+### Key Workflow
+
+1. Record with the System Trace template.
+2. Focus on the main thread lane.
+3. Look for:
+   - **Thread blocks**: main thread waiting on locks, semaphores, or dispatch queues
+   - **VM faults**: page faults from memory-mapped files or large allocations
+   - **Context switches**: excessive switching between threads
+
+This is the most advanced template — use it after Time Profiler when you
+need OS-level detail.
+
+## xctrace CLI
+
+### Recording
+
+```bash
+# Record Time Profiler trace
+xcrun xctrace record \
+    --template "Time Profiler" \
+    --device "iPhone" \
+    --output ~/traces/profile.trace \
+    --time-limit 30s \
+    --launch com.example.MyApp
+
+# Record Allocations trace for a running app
+xcrun xctrace record \
+    --template "Allocations" \
+    --device "iPhone" \
+    --output ~/traces/alloc.trace \
+    --attach com.example.MyApp
+
+# Record with multiple instruments
+xcrun xctrace record \
+    --template "Time Profiler" \
+    --template "Allocations" \
+    --output ~/traces/combined.trace \
+    --launch com.example.MyApp
+```
+
+### Exporting Data
+
+```bash
+# List available tables in a trace
+xcrun xctrace export --input profile.trace --toc
+
+# Export specific table as XML
+xcrun xctrace export --input profile.trace \
+    --xpath '/trace-toc/run/data/table[@schema="time-profile"]'
+
+# Export to a file
+xcrun xctrace export --input profile.trace \
+    --xpath '/trace-toc/run/data/table[@schema="time-profile"]' \
+    --output profile_data.xml
+```
+
+### Listing Resources
+
+```bash
+# Available templates
+xcrun xctrace list templates
+
+# Connected devices
+xcrun xctrace list devices
+
+# Running processes on a device
+xcrun xctrace list processes --device "iPhone"
+```
+
+## Custom Instruments with os_signpost
+
+### Emitting Signposts for Instruments
+
+```swift
+import os
+
+let signposter = OSSignposter(subsystem: "com.example.app", category: "Networking")
+
+func fetchUser(id: String) async throws -> User {
+    let state = signposter.beginInterval("fetchUser", id: signposter.makeSignpostID())
+    defer { signposter.endInterval("fetchUser", state) }
+
+    let (data, _) = try await URLSession.shared.data(from: userURL(id))
+    signposter.emitEvent("dataReceived", "\(data.count) bytes")
+
+    return try JSONDecoder().decode(User.self, from: data)
+}
+```
+
+### Viewing in Instruments
+
+1. Open Instruments with the **os_signpost** or **Points of Interest** template.
+2. Your custom intervals appear as labeled bars in the timeline.
+3. Events appear as point markers.
+4. Filter by subsystem or category to isolate your signposts.
+
+### Integration with MetricKit
+
+Signposts emitted through `MXMetricManager.makeLogHandle(category:)` are
+also reported in MetricKit payloads. See the `metrickit-diagnostics` skill
+for details on custom signpost metrics.
+
+## Automation and CI Integration
+
+### Performance Baselines with xctrace
+
+Create a shell script for CI:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+APP_BUNDLE="build/MyApp.app"
+TRACE_OUTPUT="traces/ci_profile_$(date +%s).trace"
+TEMPLATE="Time Profiler"
+
+# Record trace
+xcrun xctrace record \
+    --template "$TEMPLATE" \
+    --output "$TRACE_OUTPUT" \
+    --time-limit 60s \
+    --launch "$APP_BUNDLE"
+
+# Export data for analysis
+xcrun xctrace export \
+    --input "$TRACE_OUTPUT" \
+    --toc > "traces/toc.xml"
+
+echo "Trace saved to $TRACE_OUTPUT"
+```
+
+### XCTest Performance Metrics
+
+Complement Instruments with in-test measurements:
+
+```swift
+func testScrollPerformance() {
+    let app = XCUIApplication()
+    app.launch()
+
+    let measureOptions = XCTMeasureOptions()
+    measureOptions.iterationCount = 5
+
+    measure(metrics: [
+        XCTClockMetric(),
+        XCTCPUMetric(),
+        XCTMemoryMetric(),
+        XCTStorageMetric()
+    ], options: measureOptions) {
+        app.swipeUp()
+        app.swipeDown()
+    }
+}
+```
+
+Set performance baselines in Xcode to automatically flag regressions in CI.

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/debugging-instruments/references/lldb-patterns.md

@@ -0,0 +1,298 @@
+# LLDB Patterns Reference
+
+Complete LLDB command reference for iOS debugging. Companion to the main `debugging-instruments` skill.
+
+## Contents
+
+- [Inspection Commands](#inspection-commands)
+- [Breakpoint Patterns](#breakpoint-patterns)
+- [Expression Evaluation](#expression-evaluation)
+- [Watchpoints](#watchpoints)
+- [Thread and Stack Navigation](#thread-and-stack-navigation)
+- [Memory Inspection](#memory-inspection)
+- [Custom Type Summaries](#custom-type-summaries)
+- [Python Scripting](#python-scripting)
+- [Useful Symbolic Breakpoints](#useful-symbolic-breakpoints)
+- [LLDB Init File](#lldb-init-file)
+
+## Inspection Commands
+
+### po vs p vs v
+
+| Command | Mechanism | Side Effects | Speed |
+|---------|-----------|--------------|-------|
+| `po expr` | Calls `debugDescription` via expression eval | Yes — runs code | Slow |
+| `p expr` | LLDB formatter on expression result | Yes — runs code | Medium |
+| `v varname` | Reads frame memory directly | No | Fast |
+
+```text
+(lldb) po myArray                      # Calls CustomDebugStringConvertible
+(lldb) p myArray                       # Shows type + formatted value
+(lldb) v myArray                       # Fastest, no code execution
+(lldb) v myArray[0]                    # Access elements directly
+(lldb) v self.viewModel.state          # Dot-path into properties
+```
+
+Use `v` as the default. Fall back to `po` when you need `debugDescription`
+or custom string output. Use `p` when you need type information.
+
+### Register and Memory
+
+```text
+(lldb) register read                   # All registers
+(lldb) register read x0 x1            # Specific registers (ARM64)
+(lldb) memory read 0x600003a04000      # Read raw memory
+(lldb) memory read -s1 -fx -c32 addr  # 32 bytes as hex
+```
+
+## Breakpoint Patterns
+
+### File and Line
+
+```text
+(lldb) br set -f ViewModel.swift -l 42
+(lldb) br set -f ViewModel.swift -l 42 -c "count > 10"
+(lldb) br set -f ViewModel.swift -l 42 --one-shot true   # Delete after first hit
+```
+
+### Function and Method Names
+
+```text
+(lldb) br set -n viewDidLoad                     # Any function named viewDidLoad
+(lldb) br set -n "MyApp.ViewModel.loadData()"    # Fully qualified Swift name
+(lldb) br set -S "setValue:forKey:"              # ObjC selector
+(lldb) br set -r ".*Error.*"                     # Regex match on symbol name
+(lldb) br set -r "MyModule\..*\.deinit"         # All deinits in a module
+```
+
+### Breakpoint Actions
+
+```text
+(lldb) br set -n loadData
+(lldb) br command add 1
+> po "loadData called at \(Date())"
+> bt
+> continue
+> DONE
+```
+
+### Logpoints (Auto-Continue Breakpoints)
+
+```text
+(lldb) br set -f File.swift -l 42
+(lldb) br modify 1 --auto-continue true
+(lldb) br command add 1
+> po "state = \(self.state)"
+> DONE
+```
+
+This prints the value every time line 42 is hit without stopping execution.
+Equivalent to Xcode's "Log Message" breakpoint action with auto-continue.
+
+### Listing and Managing
+
+```text
+(lldb) br list                         # Show all breakpoints
+(lldb) br disable 1                    # Disable breakpoint 1
+(lldb) br enable 1                     # Re-enable
+(lldb) br delete 1                     # Remove
+(lldb) br delete                       # Remove ALL breakpoints
+(lldb) br modify 1 -i 5               # Skip first 5 hits (ignore count)
+```
+
+## Expression Evaluation
+
+### Swift Expressions
+
+```text
+(lldb) expr myArray.count
+(lldb) expr myArray.filter { $0.isActive }.count
+(lldb) expr let result = myFunc(); print(result)
+(lldb) e -l swift -- import Foundation
+(lldb) e -l swift -- self.title = "Debug Title"
+```
+
+### Objective-C Expressions (for UIKit internals)
+
+```text
+(lldb) e -l objc -- (void)[CATransaction flush]
+(lldb) e -l objc -- (void)[[UIApplication sharedApplication] _performMemoryWarning]
+(lldb) e -l objc -- (BOOL)[(id)0x7fc... isKindOfClass:[UIView class]]
+(lldb) e -l objc -- (void)[0x7fc... recursiveDescription]   # View hierarchy dump
+```
+
+### Modifying State at Runtime
+
+```text
+(lldb) e self.debugLabel.text = "Modified in debugger"
+(lldb) e self.view.backgroundColor = UIColor.red
+(lldb) e -l objc -- (void)[CATransaction flush]   # Force redraw
+```
+
+### Calling Functions
+
+```text
+(lldb) e self.viewModel.reset()
+(lldb) e UserDefaults.standard.set(true, forKey: "debug_mode")
+(lldb) e NotificationCenter.default.post(name: .init("DebugReload"), object: nil)
+```
+
+## Watchpoints
+
+```text
+(lldb) w set v self.score                          # Watch for writes
+(lldb) w set v self.score -w read                 # Watch for reads
+(lldb) w set v self.score -w read_write           # Watch both
+(lldb) w set e -- 0x600003a04000                   # Watch memory address
+(lldb) w modify 1 -c "self.score > 100"           # Conditional
+(lldb) w list                                      # Show active watchpoints
+(lldb) w delete 1                                  # Remove
+```
+
+Hardware watchpoint limit on Apple Silicon: 4 watchpoints. Use them
+sparingly for tracking unexpected mutations.
+
+## Thread and Stack Navigation
+
+```text
+(lldb) thread list                                 # All threads with status
+(lldb) thread select 3                             # Switch to thread 3
+(lldb) bt                                          # Backtrace current thread
+(lldb) bt all                                      # Backtrace every thread
+(lldb) bt 5                                        # Show only top 5 frames
+(lldb) frame select 2                              # Jump to frame #2
+(lldb) frame info                                  # Current frame info
+(lldb) frame variable                              # All variables in frame
+(lldb) up                                          # Move up one frame
+(lldb) down                                        # Move down one frame
+```
+
+### Thread Return (skip execution)
+
+```text
+(lldb) thread return                               # Return from current frame
+(lldb) thread return false                         # Return false from a Bool func
+```
+
+Use `thread return` to skip the rest of a function during debugging.
+Useful for bypassing a crash or testing a different code path.
+
+## Memory Inspection
+
+```text
+(lldb) memory read 0x600003a04000                  # Default format
+(lldb) memory read -s4 -fx -c8 addr               # 8 x 4-byte hex words
+(lldb) memory read -f s addr                       # Read as C string
+(lldb) memory find 0x100000 0x200000 -e "DEADBEEF" # Search memory range
+(lldb) image lookup -a 0x100004500                 # Symbol at address
+(lldb) image lookup -n loadData                    # Address of symbol
+(lldb) image list                                  # All loaded images/frameworks
+```
+
+### Swift Metadata Inspection
+
+```text
+(lldb) e -l swift -- print(type(of: myObject))
+(lldb) e -l swift -- dump(myObject)                # Full mirror dump
+(lldb) e -l swift -- Mirror(reflecting: myObject).children.map { $0.label }
+```
+
+## Custom Type Summaries
+
+Add type summaries to `.lldbinit` for cleaner debugger output:
+
+```text
+# ~/.lldbinit
+
+# Show CLLocationCoordinate2D as "lat, lon"
+type summary add CLLocationCoordinate2D \
+    --summary-string "lat=${var.latitude}, lon=${var.longitude}"
+
+# Show Date as readable string
+type summary add Foundation.Date \
+    --summary-string "${var.timeIntervalSinceReferenceDate} secs since 2001"
+
+# Custom summary for your own types
+type summary add MyApp.UserProfile \
+    --summary-string "User(${var.name}, id=${var.id})"
+```
+
+## Python Scripting
+
+### Inline Python
+
+```text
+(lldb) script import os
+(lldb) script print(os.getpid())
+(lldb) script lldb.debugger.GetSelectedTarget().GetProcess().GetNumThreads()
+```
+
+### Custom Python Command
+
+Create `~/lldb_commands/dump_views.py`:
+
+```python
+import lldb
+
+def dump_view_hierarchy(debugger, command, result, internal_dict):
+    """Dump the key window's view hierarchy."""
+    target = debugger.GetSelectedTarget()
+    process = target.GetProcess()
+    thread = process.GetSelectedThread()
+    frame = thread.GetSelectedFrame()
+
+    expr = '(NSString *)[[UIApplication sharedApplication].keyWindow recursiveDescription]'
+    value = frame.EvaluateExpression(expr)
+    result.AppendMessage(str(value.GetObjectDescription()))
+
+def __lldb_init_module(debugger, internal_dict):
+    debugger.HandleCommand(
+        'command script add -f dump_views.dump_view_hierarchy dump_views'
+    )
+```
+
+Load in `.lldbinit`:
+
+```text
+command script import ~/lldb_commands/dump_views.py
+```
+
+Then use in LLDB:
+
+```text
+(lldb) dump_views
+```
+
+## Useful Symbolic Breakpoints
+
+Set these in Xcode's Breakpoint Navigator for common debugging scenarios:
+
+| Symbol | Purpose |
+|--------|---------|
+| `UIViewAlertForUnsatisfiableConstraints` | Auto Layout constraint conflicts |
+| `swift_willThrow` | Break on all Swift throws |
+| `malloc_error_break` | Heap corruption detection |
+| `_UITraitCollectionChangeObserverNotify` | Track trait collection changes |
+| `objc_exception_throw` | Break on ObjC exceptions |
+| `-[UIApplication _performMemoryWarning]` | Memory warning simulation |
+| `NSInternalInconsistencyException` | Foundation assertion failures |
+
+## LLDB Init File
+
+Place commonly used configuration in `~/.lldbinit`:
+
+```text
+# Custom aliases
+command alias -- pp e -l swift -- import Foundation
+command alias -- pjson e -l swift -- print(String(data: try! JSONSerialization.data(withJSONObject: %1, options: .prettyPrinted), encoding: .utf8)!)
+
+# Type summaries
+type summary add --summary-string "${var.rawValue}" -x "^.*RawRepresentable$"
+
+# Load custom scripts
+command script import ~/lldb_commands/dump_views.py
+
+# Settings
+settings set target.language swift
+settings set frame-format "frame #${frame.index}: ${frame.pc}{ ${module.file.basename}{\`${function.name-with-args}{${frame.no-debug}}}}\n"
+```