1# Instruments Trace Analysis
2 
3Use this reference whenever the user references an Xcode Instruments `.trace`
4file. A target SwiftUI source file is **optional** — if provided, you can
5cite specific lines; without one, the trace still surfaces view names,
6hot symbols, and high-severity events that tell the user where to look.
7 
8The bundled parser reads five lanes for SwiftUI responsiveness (Time
9Profiler, Hangs, Animation Hitches, SwiftUI updates, and the SwiftUI
10cause graph) and exposes three discovery modes (`--list-logs`,
11`--list-signposts`, `--fanin-for`) plus a `--window` flag so the agent
12can focus analysis on a precise slice of the trace.
13 
14## When to invoke
15 
16Any of these signals:
17 
18- Message contains a path ending in `.trace`.
19- User mentions "hangs", "hitches", "jank", "slow view", or performance
20  issues alongside an Instruments recording.
21- User asks to focus analysis "after / before / between / during" a log
22  message or signpost.
23 
24Triggering does **not** require a SwiftUI source file. If one is present
25you'll ground recommendations in specific lines; if not, base them on the
26view names and symbols the trace reveals.
27 
28## The three CLI modes
29 
30The scripts live alongside this skill at `scripts/` and need only the
31Python 3 stdlib + `xctrace` (ships with Xcode at `/usr/bin/xctrace`).
32 
33### 1. Full analysis (default)
34 
35```bash
36python3 "${SKILL_DIR}/scripts/analyze_trace.py" \
37  --trace "/path/to/file.trace" \
38  --top 10 --top-hitches 5 \
39  [--window START_MS:END_MS] \
40  --json-only
41```
42 
43- `--json-only` gives you structured data; omit for JSON + markdown
44  summary; `--markdown-only` is for pasting a digest into the chat.
45- `--output <path>` writes `<path>.json` and `<path>.md` instead of stdout.
46- `--window START_MS:END_MS` (optional) restricts every lane and every
47  correlation to that time slice.
48- `--run N` selects a specific run when the trace contains more than one
49  recording session. Single-run traces don't need it; multi-run traces
50  require it and will error with the available run numbers if omitted.
51  Use `--list-runs` to dump per-run metadata (template, duration,
52  start/end dates, schemas) before analyzing.
53 
54### 2. `--list-logs` — find os_log timestamps
55 
56```bash
57python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> --list-logs \
58  [--log-subsystem com.myapp.net] \
59  [--log-category "Network"] \
60  [--log-type Fault] \
61  [--log-message-contains "loaded feed"] \
62  [--log-limit 10] \
63  [--window START_MS:END_MS]
64```
65 
66Returns JSON `{ "logs": [...], "count": N }` where each log entry includes
67`time_ms`, `type`, `subsystem`, `category`, `process`, and the formatted
68`message` (with args substituted) + raw `format_string`. All filters are
69AND-combined; `--log-message-contains` is case-insensitive substring match.
70 
71### 3. `--list-signposts` — find signpost intervals
72 
73```bash
74python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> --list-signposts \
75  [--signpost-name-contains "ImageDecode"] \
76  [--signpost-subsystem com.myapp.feed] \
77  [--signpost-category "Rendering"] \
78  [--window START_MS:END_MS]
79```
80 
81Returns JSON `{ "intervals": [...], "events": [...] }`. Intervals are
82paired `begin`/`end` signposts with `start_ms`, `end_ms`, `duration_ms`,
83`name`, `subsystem`, `category`, `process`, `signpost_id`. Single-point
84events (and any unpaired begins) go into `events`. All filters are
85AND-combined; `--signpost-name-contains` is case-insensitive substring
86match.
87 
88### 4. `--fanin-for` — who keeps invalidating this view?
89 
90```bash
91python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
92  --fanin-for "TextStyleModifier" \
93  [--window START_MS:END_MS] \
94  [--top 10]
95```
96 
97Returns JSON `{ "matches": [...] }`. Each match names a destination node
98whose fmt string contains the substring (case-insensitive) and lists its
99top incoming source nodes ranked by edge count. Use this after the
100`swiftui` lane names an expensive view and you want to know *why it keeps
101being invalidated*. For the example above, the top source is
102`closure #1 in UserDefaultObserver.Target.GraphAttribute.send()` — the
103canonical signature of an `@AppStorage` / `UserDefaults` feedback storm.
104 
105## Composition pattern — scoping to a slice
106 
107When the user says something like "focus on X", "between A and B", or
108"during signpost Y", compose the three modes:
109 
1101. **Discover** — call `--list-logs` or `--list-signposts` with filters
111   that match the user's description. Pick the right entries.
1122. **Build the window** — take `time_ms` (logs) or `start_ms`/`end_ms`
113   (intervals) and form `--window START:END`.
1143. **Analyse** — call the default mode with `--window`.
115 
116Examples:
117 
118- *"Focus on the section after the log saying 'loaded feed'."*
119  → `--list-logs --log-message-contains "loaded feed"`, take the entry's
120  `time_ms`, set window = `[that_ms, end_of_trace_ms]` (or use the trace
121  `duration_s × 1000`).
122- *"Between the 'begin-sync' log and the 'done-sync' log."*
123  → Two `--list-logs` calls (or one with a broader filter), pick the two
124  timestamps, set window = `[first, second]`.
125- *"During the signpost 'ImageDecode'."*
126  → `--list-signposts --signpost-name-contains "ImageDecode"`, pick the
127  interval, set window = `[start_ms, end_ms]`.
128 
129## JSON shape
130 
131```json
132{
133  "trace": "...",
134  "xctrace_version": "26.4 (...)",
135  "template": "SwiftUI",
136  "duration_s": 14.83,
137  "schemas_available": [...],
138  "lanes": [
139    { "lane": "time-profiler", "available": true, "schema_used": "time-profile",
140      "metrics": { "total_samples": N, "total_weight_ms": ms, "processes": [...] },
141      "top_offenders": [ { "symbol", "weight_ms", "percent", "samples", "thread" } ] },
142    { "lane": "hangs", "available": true, "schema_used": "potential-hangs",
143      "metrics": { "count", "total_duration_ms", "worst_duration_ms",
144                   "severity_buckets": {"lt_250ms","250ms_1s","gt_1s"} },
145      "top_offenders": [ { "start_ms", "duration_ms", "hang_type", "thread" } ] },
146    { "lane": "hitches", "available": true, "schema_used": "hitches",
147      "metrics": { "count", "total_hitch_ms", "worst_hitch_ms",
148                   "narrative_breakdown": {...}, "system_hitches", "app_hitches" },
149      "top_offenders": [ { "start_ms", "hitch_duration_ms", "narrative", "is_system" } ] },
150    { "lane": "swiftui", "available": true, "schemas_used": [...],
151      "metrics": { "total_events", "unique_views", "total_duration_ms",
152                   "severity_breakdown": {"Very Low":N,"Moderate":N,"High":N},
153                   "update_type_breakdown": {"View Body Updates":N, ...} },
154      "top_offenders": [ { "view", "total_ms", "count", "avg_ms" } ],
155      "high_severity_events": [ { "view", "severity", "duration_ms", "category",
156                                   "update_type", "description" } ] },
157    { "lane": "swiftui-causes", "available": true, "schema_used": "swiftui-causes",
158      "metrics": { "total_edges", "unique_sources", "unique_destinations",
159                   "top_labels": {...} },
160      "top_sources":      [ { "source", "edges", "top_destinations": [...] } ],
161      "top_destinations": [ { "destination", "edges", "top_sources":      [...] } ] }
162  ],
163  "correlations": [
164    {
165      "trigger": { "lane": "hangs"|"hitches", "start_ms", "end_ms", "duration_ms",
166                   "hang_type"|"frame_duration_ms" },
167      "time_profiler_main_thread": {
168        "samples_in_window": N, "samples_on_main": M,
169        "main_running_coverage_pct": 0–100,
170        "hot_symbols": [ { "symbol", "samples", "weight_ms", "percent_of_main" } ]
171      },
172      "swiftui_overlapping_updates": [ { "view", "duration_ms", "start_ms" } ]
173    }
174  ]
175}
176```
177 
178## Interpretation guide
179 
180### `main_running_coverage_pct` is the key diagnostic
181 
182Time Profiler samples the main thread every ~1ms. For a correlation window
183of `N` ms, you'd expect ~`N` main-thread running samples if main were fully
184CPU-bound. Coverage is the ratio of observed main-thread samples to that
185expectation.
186 
187- **< 25% coverage** → main thread was **blocked** (I/O, lock, sync XPC,
188  `Task.sleep`, waiting on an actor-isolated call). The `hot_symbols` you
189  do see are the moments main *was* executing — look there for the code
190  that *initiates* the blocking work, not the work itself. Common fix:
191  move to a background executor / `nonisolated` / `Task.detached`.
192- **≥ 75% coverage** → main was **CPU-bound** the whole time. `hot_symbols`
193  point directly at the expensive work. Common fixes: hoist computation
194  out of view bodies, cache derived values, avoid per-frame allocation,
195  debounce `onChange`.
196- **25–75%** → mix. Usually computation plus intermittent I/O; show both
197  hot symbols and note that main was partially blocked.
198 
199### High-severity SwiftUI events → reference routing
200 
201When `swiftui.high_severity_events[].description` is one of:
202 
203| description      | Likely cause              | Route to                            |
204|------------------|---------------------------|-------------------------------------|
205| `onChange`       | Expensive `.onChange` body | `references/performance-patterns.md`, `references/state-management.md` |
206| `Gesture`        | Heavy gesture handler     | `references/performance-patterns.md` |
207| `Action Callback`| Button/tap handler work   | `references/performance-patterns.md` |
208| `Update`         | View body recomputation   | `references/view-structure.md`, `references/performance-patterns.md` |
209| `Creation`       | View init cost            | `references/view-structure.md`      |
210| `Layout`         | GeometryReader churn      | `references/layout-best-practices.md` |
211 
212### Mapping trace findings to source code
213 
214If the user gave you a specific file, use it to confirm/cite. If they didn't, the trace itself tells you which views and symbols to look up.
215 
2161. **From `swiftui.top_offenders` and `high_severity_events`**, use the
217   `view` string as your search key. If a target file is open, grep it;
218   if not, recommend the user grep their project for that type or the
219   module name. A partial match (prefix / generic stripping) means it's
220   probably a subview.
2212. **From `correlations[].time_profiler_main_thread.hot_symbols`**, treat
222   symbols starting with the user's module name (or in Swift free-function
223   form) as candidates. System frames (`swift_`, `dyld`, `objc_`, `CA*`,
224   `CF*`, `NS*`, `__open`, `pthread*`) identify *what* the code was doing
225   but the user-code caller one frame up is typically what to fix — say
226   so and, if you can, suggest searching the project for callers of the
227   equivalent Swift API (e.g. `__open` → `FileHandle` / `Data(contentsOf:)` /
228   `JSONDecoder.decode(from: Data)` sites).
2293. **From `hitches[].narrative`**, Apple pre-attributes each hitch. The
230   string `"Potentially expensive app update(s)"` means SwiftUI blamed the
231   app (so user code is in scope); absence of narrative usually means it
232   was a system hitch or below the threshold.
2334. **Correlating hitches with SwiftUI updates**: the
234   `swiftui_overlapping_updates` list on each hitch names the views that
235   were actively rendering when the frame dropped. Prioritise those.
236 
237### Cause graph: finding *why* updates keep happening
238 
239The `swiftui` lane tells you *what* is expensive; the `swiftui-causes`
240lane tells you *why* it keeps being triggered. Each edge is "source node
241propagated to destination node" in SwiftUI's attribute graph.
242 
243Signatures to watch for in `top_sources`:
244 
245- **`closure #1 in UserDefaultObserver.Target.GraphAttribute.send()`** —
246  an `@AppStorage` / `UserDefaults` write is fanning out to every reader.
247  If the destination list contains multiple `@AppStorage <Type>.<prop>`
248  entries with thousands of edges each, you have a feedback storm. Fix
249  by reading each key once at a high level and passing values down, or
250  wrapping settings in a single `@Observable` so only genuine readers
251  invalidate. Route to `references/state-management.md` and
252  `references/performance-patterns.md`.
253- **`EnvironmentWriter: …`** with thousands of edges — a modifier (often
254  `.hoverEffect`, custom environment keys) is applied too widely and
255  being re-installed during every layout pass. Route to
256  `references/view-structure.md`.
257- **`View Creation / Reuse`** as the #1 source — the hierarchy is
258  replacing children rather than mutating in place. Look for ID
259  instability (missing/unstable `.id(…)` on ForEach, type-erased
260  `AnyView` wrappers, conditional structure swaps). Route to
261  `references/list-patterns.md` and `references/view-structure.md`.
262 
263When a specific view in `swiftui.high_severity_events` keeps showing up,
264run `--fanin-for "<view name>"` to see the ranked list of sources
265invalidating it.
266 
267### Picking targets from a full-trace analysis
268 
269Prioritise from most actionable to least:
270 
2711. **Any `hangs` with `main_running_coverage_pct < 25%`** — these are
272   blocking-I/O smells; nearly always fixable by moving work off-main.
2732. **Any `hangs` with `main_running_coverage_pct ≥ 75%`** — CPU-bound
274   main-thread work; fix the top `hot_symbols`.
2753. **`swiftui-causes.top_sources` with > ~1k edges** — structural
276   invalidation bugs (feedback storms, over-applied modifiers). These
277   are often cheaper to fix than per-view optimisations and collapse
278   many downstream high-severity updates at once.
2794. **`hitches` with `narrative == "Potentially expensive app update(s)"`**
280   and overlapping `swiftui_overlapping_updates` — specific views to
281   restructure.
2825. **`swiftui.high_severity_events`** — `onChange`, `Gesture`, or `Action
283   Callback` with `duration_ms > ~16` are frame-dropping handlers. For
284   any that keep firing, run `--fanin-for` to find the source.
2856. **`swiftui.top_offenders`** — heaviest views by total body time, even
286   without triggering hitches; candidates for view extraction or
287   memoisation (`equatable`, `@ViewBuilder` extraction).
288 
289## Recommended output format for the user
290 
291After running the parser, structure your response as:
292 
2931. **One-line summary** — "Found N hangs, worst Wms; K hitches; J high-severity SwiftUI updates."
2942. **Root-cause findings** — per prioritised target (see above), one paragraph with the trace evidence (coverage %, hot symbol, overlapping view) and a citation from `references/…` for the fix pattern.
2953. **Plan** — numbered, file-specific edits. Cite line numbers in the user's Swift file when you know them. Don't edit the file unless the user asked for edits.
296