playbook/antigravity-awesome-skills/skills/swiftui-expert-skill/references/trace-analysis.md

Instruments Trace Analysis

Use this reference whenever the user references an Xcode Instruments .trace file. A target SwiftUI source file is optional — if provided, you can cite specific lines; without one, the trace still surfaces view names, hot symbols, and high-severity events that tell the user where to look.

The bundled parser reads five lanes for SwiftUI responsiveness (Time Profiler, Hangs, Animation Hitches, SwiftUI updates, and the SwiftUI cause graph) and exposes three discovery modes (--list-logs, --list-signposts, --fanin-for) plus a --window flag so the agent can focus analysis on a precise slice of the trace.

When to invoke

Any of these signals:

• Message contains a path ending in .trace.
• User mentions "hangs", "hitches", "jank", "slow view", or performance issues alongside an Instruments recording.
• User asks to focus analysis "after / before / between / during" a log message or signpost.

Triggering does not require a SwiftUI source file. If one is present you'll ground recommendations in specific lines; if not, base them on the view names and symbols the trace reveals.

The three CLI modes

The scripts live alongside this skill at scripts/ and need only the Python 3 stdlib + xctrace (ships with Xcode at /usr/bin/xctrace).

1. Full analysis (default)

python3 "${SKILL_DIR}/scripts/analyze_trace.py" \
  --trace "/path/to/file.trace" \
  --top 10 --top-hitches 5 \
  [--window START_MS:END_MS] \
  --json-only

• --json-only gives you structured data; omit for JSON + markdown summary; --markdown-only is for pasting a digest into the chat.
• --output <path> writes <path>.json and <path>.md instead of stdout.
• --window START_MS:END_MS (optional) restricts every lane and every correlation to that time slice.
• --run N selects a specific run when the trace contains more than one recording session. Single-run traces don't need it; multi-run traces require it and will error with the available run numbers if omitted. Use --list-runs to dump per-run metadata (template, duration, start/end dates, schemas) before analyzing.

2. --list-logs — find os_log timestamps

python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> --list-logs \
  [--log-subsystem com.myapp.net] \
  [--log-category "Network"] \
  [--log-type Fault] \
  [--log-message-contains "loaded feed"] \
  [--log-limit 10] \
  [--window START_MS:END_MS]

Returns JSON { "logs": [...], "count": N } where each log entry includes time_ms, type, subsystem, category, process, and the formatted message (with args substituted) + raw format_string. All filters are AND-combined; --log-message-contains is case-insensitive substring match.

3. --list-signposts — find signpost intervals

python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> --list-signposts \
  [--signpost-name-contains "ImageDecode"] \
  [--signpost-subsystem com.myapp.feed] \
  [--signpost-category "Rendering"] \
  [--window START_MS:END_MS]

Returns JSON { "intervals": [...], "events": [...] }. Intervals are paired begin/end signposts with start_ms, end_ms, duration_ms, name, subsystem, category, process, signpost_id. Single-point events (and any unpaired begins) go into events. All filters are AND-combined; --signpost-name-contains is case-insensitive substring match.

4. --fanin-for — who keeps invalidating this view?

python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
  --fanin-for "TextStyleModifier" \
  [--window START_MS:END_MS] \
  [--top 10]

Returns JSON { "matches": [...] }. Each match names a destination node whose fmt string contains the substring (case-insensitive) and lists its top incoming source nodes ranked by edge count. Use this after the swiftui lane names an expensive view and you want to know why it keeps being invalidated. For the example above, the top source is closure #1 in UserDefaultObserver.Target.GraphAttribute.send() — the canonical signature of an @AppStorage / UserDefaults feedback storm.

Composition pattern — scoping to a slice

When the user says something like "focus on X", "between A and B", or "during signpost Y", compose the three modes:

1. Discover — call --list-logs or --list-signposts with filters that match the user's description. Pick the right entries.
2. Build the window — take time_ms (logs) or start_ms/end_ms (intervals) and form --window START:END.
3. Analyse — call the default mode with --window.

Examples:

• "Focus on the section after the log saying 'loaded feed'." → --list-logs --log-message-contains "loaded feed", take the entry's time_ms, set window = [that_ms, end_of_trace_ms] (or use the trace duration_s × 1000).
• "Between the 'begin-sync' log and the 'done-sync' log." → Two --list-logs calls (or one with a broader filter), pick the two timestamps, set window = [first, second].
• "During the signpost 'ImageDecode'." → --list-signposts --signpost-name-contains "ImageDecode", pick the interval, set window = [start_ms, end_ms].

JSON shape

{
  "trace": "...",
  "xctrace_version": "26.4 (...)",
  "template": "SwiftUI",
  "duration_s": 14.83,
  "schemas_available": [...],
  "lanes": [
    { "lane": "time-profiler", "available": true, "schema_used": "time-profile",
      "metrics": { "total_samples": N, "total_weight_ms": ms, "processes": [...] },
      "top_offenders": [ { "symbol", "weight_ms", "percent", "samples", "thread" } ] },
    { "lane": "hangs", "available": true, "schema_used": "potential-hangs",
      "metrics": { "count", "total_duration_ms", "worst_duration_ms",
                   "severity_buckets": {"lt_250ms","250ms_1s","gt_1s"} },
      "top_offenders": [ { "start_ms", "duration_ms", "hang_type", "thread" } ] },
    { "lane": "hitches", "available": true, "schema_used": "hitches",
      "metrics": { "count", "total_hitch_ms", "worst_hitch_ms",
                   "narrative_breakdown": {...}, "system_hitches", "app_hitches" },
      "top_offenders": [ { "start_ms", "hitch_duration_ms", "narrative", "is_system" } ] },
    { "lane": "swiftui", "available": true, "schemas_used": [...],
      "metrics": { "total_events", "unique_views", "total_duration_ms",
                   "severity_breakdown": {"Very Low":N,"Moderate":N,"High":N},
                   "update_type_breakdown": {"View Body Updates":N, ...} },
      "top_offenders": [ { "view", "total_ms", "count", "avg_ms" } ],
      "high_severity_events": [ { "view", "severity", "duration_ms", "category",
                                   "update_type", "description" } ] },
    { "lane": "swiftui-causes", "available": true, "schema_used": "swiftui-causes",
      "metrics": { "total_edges", "unique_sources", "unique_destinations",
                   "top_labels": {...} },
      "top_sources":      [ { "source", "edges", "top_destinations": [...] } ],
      "top_destinations": [ { "destination", "edges", "top_sources":      [...] } ] }
  ],
  "correlations": [
    {
      "trigger": { "lane": "hangs"|"hitches", "start_ms", "end_ms", "duration_ms",
                   "hang_type"|"frame_duration_ms" },
      "time_profiler_main_thread": {
        "samples_in_window": N, "samples_on_main": M,
        "main_running_coverage_pct": 0–100,
        "hot_symbols": [ { "symbol", "samples", "weight_ms", "percent_of_main" } ]
      },
      "swiftui_overlapping_updates": [ { "view", "duration_ms", "start_ms" } ]
    }
  ]
}

Interpretation guide

main_running_coverage_pct is the key diagnostic

Time Profiler samples the main thread every ~1ms. For a correlation window of N ms, you'd expect ~N main-thread running samples if main were fully CPU-bound. Coverage is the ratio of observed main-thread samples to that expectation.

• < 25% coverage → main thread was blocked (I/O, lock, sync XPC, Task.sleep, waiting on an actor-isolated call). The hot_symbols you do see are the moments main was executing — look there for the code that initiates the blocking work, not the work itself. Common fix: move to a background executor / nonisolated / Task.detached.
• ≥ 75% coverage → main was CPU-bound the whole time. hot_symbols point directly at the expensive work. Common fixes: hoist computation out of view bodies, cache derived values, avoid per-frame allocation, debounce onChange.
• 25–75% → mix. Usually computation plus intermittent I/O; show both hot symbols and note that main was partially blocked.

High-severity SwiftUI events → reference routing

When swiftui.high_severity_events[].description is one of:

description	Likely cause	Route to
onChange	Expensive .onChange body	references/performance-patterns.md, references/state-management.md
Gesture	Heavy gesture handler	references/performance-patterns.md
Action Callback	Button/tap handler work	references/performance-patterns.md
Update	View body recomputation	references/view-structure.md, references/performance-patterns.md
Creation	View init cost	references/view-structure.md
Layout	GeometryReader churn	references/layout-best-practices.md

Mapping trace findings to source code

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

1. From swiftui.top_offenders and high_severity_events, use the view string as your search key. If a target file is open, grep it; if not, recommend the user grep their project for that type or the module name. A partial match (prefix / generic stripping) means it's probably a subview.
2. From correlations[].time_profiler_main_thread.hot_symbols, treat symbols starting with the user's module name (or in Swift free-function form) as candidates. System frames (swift_, dyld, objc_, CA*, CF*, NS*, __open, pthread*) identify what the code was doing but the user-code caller one frame up is typically what to fix — say so and, if you can, suggest searching the project for callers of the equivalent Swift API (e.g. __open → FileHandle / Data(contentsOf:) / JSONDecoder.decode(from: Data) sites).
3. From hitches[].narrative, Apple pre-attributes each hitch. The string "Potentially expensive app update(s)" means SwiftUI blamed the app (so user code is in scope); absence of narrative usually means it was a system hitch or below the threshold.
4. Correlating hitches with SwiftUI updates: the swiftui_overlapping_updates list on each hitch names the views that were actively rendering when the frame dropped. Prioritise those.

Cause graph: finding why updates keep happening

The swiftui lane tells you what is expensive; the swiftui-causes lane tells you why it keeps being triggered. Each edge is "source node propagated to destination node" in SwiftUI's attribute graph.

Signatures to watch for in top_sources:

• closure #1 in UserDefaultObserver.Target.GraphAttribute.send() — an @AppStorage / UserDefaults write is fanning out to every reader. If the destination list contains multiple @AppStorage <Type>.<prop> entries with thousands of edges each, you have a feedback storm. Fix by reading each key once at a high level and passing values down, or wrapping settings in a single @Observable so only genuine readers invalidate. Route to references/state-management.md and references/performance-patterns.md.
• EnvironmentWriter: … with thousands of edges — a modifier (often .hoverEffect, custom environment keys) is applied too widely and being re-installed during every layout pass. Route to references/view-structure.md.
• View Creation / Reuse as the #1 source — the hierarchy is replacing children rather than mutating in place. Look for ID instability (missing/unstable .id(…) on ForEach, type-erased AnyView wrappers, conditional structure swaps). Route to references/list-patterns.md and references/view-structure.md.

When a specific view in swiftui.high_severity_events keeps showing up, run --fanin-for "<view name>" to see the ranked list of sources invalidating it.

Picking targets from a full-trace analysis

Prioritise from most actionable to least:

1. Any hangs with main_running_coverage_pct < 25% — these are blocking-I/O smells; nearly always fixable by moving work off-main.
2. Any hangs with main_running_coverage_pct ≥ 75% — CPU-bound main-thread work; fix the top hot_symbols.
3. swiftui-causes.top_sources with > ~1k edges — structural invalidation bugs (feedback storms, over-applied modifiers). These are often cheaper to fix than per-view optimisations and collapse many downstream high-severity updates at once.
4. hitches with narrative == "Potentially expensive app update(s)" and overlapping swiftui_overlapping_updates — specific views to restructure.
5. swiftui.high_severity_events — onChange, Gesture, or Action Callback with duration_ms > ~16 are frame-dropping handlers. For any that keep firing, run --fanin-for to find the source.
6. swiftui.top_offenders — heaviest views by total body time, even without triggering hitches; candidates for view extraction or memoisation (equatable, @ViewBuilder extraction).

Recommended output format for the user

After running the parser, structure your response as:

1. One-line summary — "Found N hangs, worst Wms; K hitches; J high-severity SwiftUI updates."
2. 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.
3. 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.