@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

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

@@ -5,6 +5,8 @@ description: "Debug iOS apps and profile performance using LLDB, Memory Graph De
 
 # 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.
+
 ## Contents
 
 - [LLDB Debugging](#lldb-debugging)
@@ -23,7 +25,7 @@ description: "Debug iOS apps and profile performance using LLDB, Memory Graph De
 ```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) 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
@@ -31,7 +33,7 @@ description: "Debug iOS apps and profile performance using LLDB, Memory Graph De
 (lldb) thread select 4          # Switch to thread #4
 ```
 
-Use `v` over `po` when you only need a local variable value — it does not
+Use `v` over `po` when you only need a local variable value  -  it does not
 execute code and cannot trigger side effects.
 
 ### Breakpoint Management
@@ -73,7 +75,7 @@ to see the change immediately without resuming execution.
 ```
 
 Watchpoints are hardware-backed (limited to ~4 on ARM). Use them to find
-unexpected mutations — the debugger stops at the exact line that changes
+unexpected mutations  -  the debugger stops at the exact line that changes
 the value.
 
 ### Symbolic Breakpoints
@@ -98,7 +100,7 @@ common diagnostics like `-[UIApplication main]` or `swift_willThrow`.
 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.
+4. Look for purple warning icons  -  these indicate leaked objects.
 5. Select a leaked object to see its reference graph and backtrace.
 
 Enable **Malloc Stack Logging** (Scheme > Diagnostics) before running so
@@ -109,7 +111,7 @@ the Memory Graph shows allocation backtraces.
 **Closure capturing self strongly:**
 
 ```swift
-// LEAK — closure holds strong reference to self
+// LEAK  -  closure holds strong reference to self
 class ProfileViewModel {
     var onUpdate: (() -> Void)?
 
@@ -120,7 +122,7 @@ class ProfileViewModel {
     }
 }
 
-// FIXED — use [weak self]
+// FIXED  -  use [weak self]
 func startObserving() {
     onUpdate = { [weak self] in
         self?.refresh()
@@ -131,7 +133,7 @@ func startObserving() {
 **Strong delegate reference:**
 
 ```swift
-// LEAK — strong delegate creates a cycle
+// LEAK  -  strong delegate creates a cycle
 protocol DataDelegate: AnyObject {
     func didUpdate()
 }
@@ -140,7 +142,7 @@ class DataManager {
     var delegate: DataDelegate?  // should be weak
 }
 
-// FIXED — weak delegate
+// FIXED  -  weak delegate
 class DataManager {
     weak var delegate: DataDelegate?
 }
@@ -149,13 +151,13 @@ class DataManager {
 **Timer retaining target:**
 
 ```swift
-// LEAK — Timer.scheduledTimer retains its target
+// 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]
+// FIXED  -  use closure-based API with [weak self]
 timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
     self?.tick()
 }
@@ -166,33 +168,43 @@ timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self]
 - **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**: Automatically detects reference cycles at runtime.
-  Run alongside Allocations for a complete picture.
+- **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.
+
 ### Malloc Stack Logging
 
-Enable in Scheme > Run > Diagnostics > Malloc Stack Logging (All
-Allocations). This records the call stack for every allocation, letting
-the Memory Graph Debugger and `leaks` CLI show where objects were created.
+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.
 
 ```bash
-# CLI leak detection
-leaks --atExit -- ./MyApp.app/MyApp
-# Symbolicate with dSYMs for readable stacks
+# Inspect an exported memory graph from Xcode or Instruments
+leaks MyApp.memgraph
 ```
 
 ## Hang Diagnostics
 
 ### Identifying Main Thread Hangs
 
-A hang occurs when the main thread is blocked for > 250ms (noticeable) or
-> 1s (severe). Common detection tools:
+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:
 
 - **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-diagnostics` skill for `MXHangDiagnostic`)
+  `metrickit` skill for `MXHangDiagnostic`)
 
 ```swift
 import os
@@ -212,7 +224,7 @@ func loadData() async {
 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.
+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.
 
@@ -230,7 +242,7 @@ func loadData() async {
 
 ### Reading Compiler Diagnostics
 
-- Start from the **first** error — subsequent errors are often cascading.
+- 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.
 
@@ -272,8 +284,8 @@ Build settings to inspect first:
 | **Leaks** | Suspect retain cycles or abandoned objects |
 | **Network** | Inspecting HTTP request/response timing and payloads |
 | **SwiftUI** | Profiling view body evaluations and update frequency |
-| **Core Animation** | Frame drops, off-screen rendering, blending issues |
-| **Energy Log** | Battery drain, background energy impact |
+| **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 |
 
@@ -283,8 +295,9 @@ Build settings to inspect first:
 # Record a trace from the command line
 xcrun xctrace record --device "My iPhone" \
     --template "Time Profiler" \
+    --instrument "Allocations" \
     --output profile.trace \
-    --launch MyApp.app
+    --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'
@@ -296,23 +309,23 @@ xcrun xctrace list templates
 xcrun xctrace list devices
 ```
 
-Use `xctrace` in CI pipelines to catch performance regressions
+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.
 
 ## Common Mistakes
 
 ### DON'T: Use print() for debugging instead of os.Logger
 
-`print()` output is not filterable, has no log levels, and is not
-automatically stripped from release builds. It pollutes the console and
-makes it impossible to isolate relevant output.
+`print()` output is unstructured, has no subsystem/category or privacy
+metadata, and is harder to filter than unified logging.
 
 ```swift
-// WRONG — unstructured, not filterable, stays in release builds
+// WRONG  -  unstructured and not filterable by subsystem/category
 print("user tapped button, state: \(viewModel.state)")
 print("network response: \(data)")
 
-// CORRECT — structured logging with Logger
+// CORRECT  -  structured logging with Logger
 import os
 
 let logger = Logger(subsystem: "com.example.app", category: "UI")
@@ -322,7 +335,7 @@ logger.info("Network response received, bytes: \(data.count)")
 ```
 
 `Logger` messages appear in Console.app with filtering by subsystem and
-category, and `.debug` messages are automatically excluded from release builds.
+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
 
@@ -331,10 +344,10 @@ 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
+// WRONG  -  open Memory Graph without enabling Malloc Stack Logging
 // Result: leaked objects visible but no allocation backtrace
 
-// CORRECT — enable BEFORE running:
+// CORRECT  -  enable BEFORE running:
 // Scheme > Run > Diagnostics > check "Malloc Stack Logging: All Allocations"
 // Then run, reproduce the leak, and open Memory Graph
 ```
@@ -345,7 +358,7 @@ In Release (optimized) builds, the compiler may inline functions, eliminate
 variables, and reorder code. LLDB cannot display optimized-away values.
 
 ```swift
-// WRONG — profiling with Debug build, debugging with Release build
+// 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
 
@@ -360,12 +373,12 @@ Breaking on every iteration wastes time and makes it hard to find the
 specific case you care about.
 
 ```swift
-// WRONG — breakpoint on line inside loop, stops 10,000 times
+// WRONG  -  breakpoint on line inside loop, stops 10,000 times
 for item in items {
     process(item)  // breakpoint here stops on EVERY item
 }
 
-// CORRECT — use a conditional breakpoint:
+// 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
 ```
@@ -373,13 +386,13 @@ for item in items {
 ### DON'T: Ignore Thread Sanitizer warnings
 
 Thread Sanitizer (TSan) warnings indicate data races that may only crash
-intermittently. They are real bugs, not false positives.
+intermittently. Treat them as real bugs unless you have isolated a tool issue.
 
 ```swift
-// WRONG — ignoring TSan warning about concurrent access
+// WRONG  -  ignoring TSan warning about concurrent access
 var cache: [String: Data] = [:]  // accessed from multiple threads
 
-// CORRECT — protect shared mutable state
+// CORRECT  -  protect shared mutable state
 actor CacheActor {
     var cache: [String: Data] = [:]
 
@@ -388,8 +401,23 @@ actor CacheActor {
 }
 ```
 
-Enable TSan: Scheme > Run > Diagnostics > Thread Sanitizer. Note: TSan
-cannot run simultaneously with Address Sanitizer.
+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
+
+When correcting another diagnostic plan, explicitly check these points:
+
+- **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.
 
 ## Review Checklist
 
@@ -399,7 +427,7 @@ cannot run simultaneously with Address Sanitizer.
 - [ ] 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 test schemes
+- [ ] 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
@@ -416,7 +444,9 @@ cannot run simultaneously with Address Sanitizer.
 - [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://sosumi.ai/tutorials/instruments)
+- [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`
-- Instruments template guide: `references/instruments-guide.md`
+- LLDB command reference: [references/lldb-patterns.md](references/lldb-patterns.md)
+- Instruments template guide: [references/instruments-guide.md](references/instruments-guide.md)

package/pipeline/skills/shared/external/debugging-instruments/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "debugging-instruments",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "I need a concise profiling plan for an iOS app that has a slow feed refresh, battery-drain complaints, and a CI job that should collect a Time Profiler trace with xctrace. Include the Instruments templates or instruments to use, and show both the basic xctrace launch command and the command shape if we add Allocations to the same Time Profiler recording.",
+      "expected_output": "A source-grounded Instruments plan that chooses current template names, profiles on device, uses Power Profiler for battery work, shows xctrace launch syntax with the required -- separator, and uses --instrument for adding Allocations to a Time Profiler recording.",
+      "files": [],
+      "expectations": [
+        "Recommends Time Profiler for CPU or slow interaction triage.",
+        "Recommends Power Profiler, not Energy Log, for battery or energy-impact analysis.",
+        "Mentions profiling on a physical device for realistic measurements.",
+        "Shows xcrun xctrace record using --launch -- before the app command or bundle path.",
+        "Uses --instrument for adding an extra instrument to a template rather than repeating --template for multiple instruments.",
+        "Does not claim that Energy Log is the current Instruments template name."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "Review this debugging plan: use the Leaks template to prove every retain cycle, run leaks --atExit -- ./MyApp.app/MyApp for our iOS build, call any 250 ms main-thread pause a severe hang, and enable Thread Sanitizer on a real iPhone test run. Correct the plan.",
+      "expected_output": "A correction-focused review that narrows leak, hang, Memory Graph, and Thread Sanitizer guidance using Apple-documented behavior.",
+      "files": [],
+      "expectations": [
+        "Explains that Leaks detects leaked allocations or isolated cycles but not every still-reachable retain cycle.",
+        "Recommends Memory Graph Debugger and Allocations generation marks for iOS retain-cycle or growth triage.",
+        "Uses exported .memgraph files with leaks for CLI memory-graph inspection instead of presenting --atExit as the default iOS app workflow.",
+        "States that a few hundred milliseconds can feel unresponsive and that Apple tools typically report main-run-loop busy periods over 250 ms.",
+        "States that Thread Sanitizer for iOS-family apps runs in Simulator, while Apple documents device support only for 64-bit macOS apps.",
+        "Does not expand into MetricKit payload handling beyond a concise handoff to the metrickit skill."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "My SwiftUI screen stutters while scrolling and I also want production hang telemetry in MetricKit plus a new Swift Testing benchmark. What should this debugging skill handle directly, and what should move to adjacent skills?",
+      "expected_output": "A boundary-aware answer that keeps Instruments and LLDB guidance in debugging-instruments while routing SwiftUI remediation, MetricKit ingestion, and Swift Testing test design to sibling skills.",
+      "files": [],
+      "expectations": [
+        "Keeps Instruments capture guidance in scope, such as SwiftUI or Animation Hitches with Time Profiler on device.",
+        "Routes SwiftUI code-level remediation patterns to the swiftui-performance skill.",
+        "Routes MetricKit subscriber setup, MXDiagnosticPayload processing, or MXHangDiagnostic ingestion details to the metrickit skill.",
+        "Routes Swift Testing or XCTest benchmark organization details to the swift-testing skill.",
+        "Mentions OSSignposter or signposts as useful instrumentation for correlating app intervals with Instruments.",
+        "Does not collapse the sibling skills by giving a full MetricKit ingestion implementation or full SwiftUI refactor recipe."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/debugging-instruments/references/instruments-guide.md

@@ -10,8 +10,8 @@ Detailed template-by-template guide for profiling iOS apps with Instruments. Com
 - [Leaks](#leaks)
 - [Network](#network)
 - [SwiftUI Instruments](#swiftui-instruments)
-- [Core Animation](#core-animation)
-- [Energy Log](#energy-log)
+- [Animation Hitches and Core Animation](#animation-hitches-and-core-animation)
+- [Power Profiler](#power-profiler)
 - [File Activity](#file-activity)
 - [System Trace](#system-trace)
 - [xctrace CLI](#xctrace-cli)
@@ -41,9 +41,9 @@ find which functions consume the most time.
 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
+   - **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.
 
@@ -51,9 +51,9 @@ find which functions consume the most time.
 
 - **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
+- **Symbol Name**: the function  -  look for your module prefix
 
-Focus on functions with high **Self Weight** — these are doing the actual work.
+Focus on functions with high **Self Weight**  -  these are doing the actual work.
 
 ### Tips
 
@@ -86,7 +86,7 @@ freed, or you need to track object lifetimes.
 - **Persistent**: long-lived allocations (singletons, caches)
 - **Transient**: short-lived allocations (autoreleased, temporary)
 
-Focus on "Created & Still Living" objects in the generation diff — these
+Focus on "Created & Still Living" objects in the generation diff  -  these
 are your potential leaks.
 
 ### Heap Growth Analysis
@@ -106,14 +106,14 @@ Enable the **Allocations List** and sort by **Persistent Bytes**. Look for:
 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
+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
+- **Cycles & Roots graph**: arrows show retain relationships  -  look for
   bidirectional arrows indicating a cycle
 
 ### Common Cycle Patterns
@@ -156,8 +156,9 @@ redraws, or identity churn in lists.
 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
+   - **Update Groups**: shows batches of view updates triggered together
+   - **Long View Body Updates**: highlights body evaluations exceeding a time threshold
+   - **Cause and Effect Graph**: traces why a view was re-evaluated
 4. Look for views with excessive body evaluations during a single interaction.
 
 ### Tips
@@ -166,18 +167,23 @@ redraws, or identity churn in lists.
 - Cross-reference with Time Profiler to see if body evaluations are expensive.
 - See the `swiftui-performance` skill for remediation patterns.
 
-## Core Animation
+## Animation Hitches and 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
+1. Record with the **Animation Hitches** template on a real device when the
+   symptom is stutter or missed frames.
+2. Add Core Animation instruments such as **Core Animation FPS**,
+   **Core Animation Commits**, or **Core Animation Activity** when you need
+   lower-level render pipeline detail.
+3. Check FPS, hitches, commits, and frame lifetime lanes for drops or long
+   commit/render work.
+4. Enable these debug options in Recording Options or Xcode view debugging:
+   - **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
 
@@ -188,15 +194,15 @@ redraws, or identity churn in lists.
 | Shadow without path | Off-screen rendering | Set `shadowPath` explicitly |
 | Large images not downsampled | High memory + slow rendering | Downsample before display |
 
-## Energy Log
+## Power Profiler
 
 **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.
+1. Record with the **Power Profiler** template on a physical device.
+2. Check power, thermal, and energy-impact lanes for high readings.
 3. Examine component breakdown:
    - CPU
    - Network
@@ -238,7 +244,7 @@ faults, system calls, and inter-process communication.
    - **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
+This is the most advanced template  -  use it after Time Profiler when you
 need OS-level detail.
 
 ## xctrace CLI
@@ -252,21 +258,21 @@ xcrun xctrace record \
     --device "iPhone" \
     --output ~/traces/profile.trace \
     --time-limit 30s \
-    --launch com.example.MyApp
+    --launch -- /path/to/MyApp.app
 
 # Record Allocations trace for a running app
 xcrun xctrace record \
     --template "Allocations" \
     --device "iPhone" \
     --output ~/traces/alloc.trace \
-    --attach com.example.MyApp
+    --attach MyApp
 
 # Record with multiple instruments
 xcrun xctrace record \
     --template "Time Profiler" \
-    --template "Allocations" \
+    --instrument "Allocations" \
     --output ~/traces/combined.trace \
-    --launch com.example.MyApp
+    --launch -- /path/to/MyApp.app
 ```
 
 ### Exporting Data
@@ -294,8 +300,8 @@ xcrun xctrace list templates
 # Connected devices
 xcrun xctrace list devices
 
-# Running processes on a device
-xcrun xctrace list processes --device "iPhone"
+# Available instruments
+xcrun xctrace list instruments
 ```
 
 ## Custom Instruments with os_signpost
@@ -308,11 +314,12 @@ 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())
+    let signpostID = signposter.makeSignpostID()
+    let state = signposter.beginInterval("fetchUser", id: signpostID)
     defer { signposter.endInterval("fetchUser", state) }
 
     let (data, _) = try await URLSession.shared.data(from: userURL(id))
-    signposter.emitEvent("dataReceived", "\(data.count) bytes")
+    signposter.emitEvent("dataReceived", id: signpostID, "\(data.count) bytes")
 
     return try JSONDecoder().decode(User.self, from: data)
 }
@@ -320,7 +327,8 @@ func fetchUser(id: String) async throws -> User {
 
 ### Viewing in Instruments
 
-1. Open Instruments with the **os_signpost** or **Points of Interest** template.
+1. Open Instruments with a Blank document, then add the **os_signpost**
+   instrument, or start from a template that includes **Points of Interest**.
 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.
@@ -328,7 +336,7 @@ func fetchUser(id: String) async throws -> User {
 ### Integration with MetricKit
 
 Signposts emitted through `MXMetricManager.makeLogHandle(category:)` are
-also reported in MetricKit payloads. See the `metrickit-diagnostics` skill
+also reported in MetricKit payloads. See the `metrickit` skill
 for details on custom signpost metrics.
 
 ## Automation and CI Integration
@@ -350,7 +358,7 @@ xcrun xctrace record \
     --template "$TEMPLATE" \
     --output "$TRACE_OUTPUT" \
     --time-limit 60s \
-    --launch "$APP_BUNDLE"
+    --launch -- "$APP_BUNDLE"
 
 # Export data for analysis
 xcrun xctrace export \

package/pipeline/skills/shared/external/debugging-instruments/references/lldb-patterns.md

@@ -21,8 +21,8 @@ Complete LLDB command reference for iOS debugging. Companion to the main `debugg
 
 | 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 |
+| `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