analyze-performance-traces

# Analyze Performance Traces

End with an evidence chain from trigger to exact source. Fix the earliest proven cause. Never turn an API name or an inclusive duration into a causal claim without checking execution context.

## Choose the evidence mode

State which mode applies before making findings:

1. **Trace-backed**: a trace is supplied or discoverable. Durations, processes, threads, and event ordering may be reported from it.
2. **Reported-finding audit**: the user supplies durations or a chain but not the artifact. Treat those details as leads. Confirm current source paths and trigger conditions; label the durations, thread, and invalidation scope unverified.
3. **Source-only**: no trace-derived lead exists. Report hypotheses, not measured bottlenecks.

Do not block a reported-finding audit merely because the original trace file is absent. If the user asks for safe implementation after the source chain is proven, proceed within authorization; require a comparable post-change trace before claiming millisecond or frame-rate improvement.

If neither a trace nor a concrete lead exists, ask for the smallest reproducible capture unless the user explicitly wants source-only analysis.

## Start safely

1. Read repository instructions, nearest area instructions, relevant architecture docs, current diff, and validation policy. Record Git baseline before editing.
2. Discover trace artifacts without printing them wholesale. For each candidate:

   ```sh
   ls -lh TRACE.json
   head -c 512 TRACE.json
   tail -c 512 TRACE.json
   ```

3. Run the bundled bounded-memory summarizer:

   ```sh
   node <skill-dir>/scripts/summarize-trace TRACE.json --top 40 --min-ms 16
   ```

4. Record trace revision/build, production versus development mode, profiling hooks, source maps, screenshots, React tracks, renderer count, and capture window. Separate profiler startup and instrumentation overhead from product work.
5. Prefer a repository-owned performance runner when it reproduces the same interaction. List scenarios first; a convenient but different scenario is not proof. In this repository, inspect `docs/conventions/testing.md` and use `pnpm perf:agent-gui -- --list-scenarios` when relevant.

### Tutti manual capture

When a new Desktop trace is required:

```sh
TUTTI_ELECTRON_REMOTE_DEBUGGING_PORT=9223 \
TUTTI_ELECTRON_JS_FLAGS=--max-old-space-size=8192 \
VITE_TUTTI_WHY_DID_YOU_RENDER=0 \
make dev-gui
```

Then capture from another terminal:

```sh
pnpm trace:desktop -- --duration 15
```

## Build one evidence chain

Work in this order:

1. **Select process/thread**: identify browser main, renderer main, compositor, workers, and GPU threads. Never sum unrelated threads.
2. **Select the window**: locate the interaction or burst containing the symptom. Quantify long tasks, layout/style, scripting, paint, frame signals, and repeated events only inside that window.
3. **Correlate timestamps**: connect input, timer, stream, resize, or observer delivery to state updates, React commits, DOM mutation, style/layout, paint, and missed frames.
4. **Measure fanout**: count repeated components, selectors, entities, DOM nodes, or geometry reads. Express multiplicative patterns such as `34 sections × 67 updates = 2,278 renders`.
5. **Map to source**: use stack URLs, source maps, named React tracks, event handlers, class names, and unique strings. Follow symbols with `rg`. Verify current source still matches the traced revision.
6. **Inspect cardinality**: use read-only DB/query inspection when scale explains the cost. Remove local paths, secrets, and personal data from durable output.
7. **State the chain**:

   ```text
   trigger → state/DOM write → churn or invalidation → render/layout fanout → paint/frame impact
   ```

Keep measured facts, source-confirmed facts, and inference visibly separate. Do not rank nested events only by inclusive time; use self time when available or label duration inclusive.

## Audit forced layout precisely

For every suspected geometry hotspot, record:

| Field          | Question                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------- |
| Trigger        | What invokes it, and how often?                                                                   |
| Invalidation   | Which DOM/style write may have dirtied layout first?                                              |
| Read/operation | `scrollHeight`, `client*`, `offset*`, rect/style read, `scrollIntoView`, virtualizer measurement? |
| Phase          | render, ref commit, layout effect, effect, observer, event, or animation frame?                   |
| Scope          | Which scroll/layout subtree must become current?                                                  |
| Semantics      | Why is the read needed: selection, bottom lock, prepend anchor, tooltip, placement?               |
| Evidence       | Trace-backed, source-confirmed path, or inference?                                                |

Apply these rules:

- A geometry API can force layout only when relevant layout is dirty. Its presence alone is not proof.
- A layout effect after a DOM-heavy commit is high risk because the read occurs before paint while invalidation is pending.
- `ResizeObserver` runs after layout calculation; a read-first callback usually consumes current geometry. Writes earlier in the same observer delivery can dirty layout again, so keep observer callbacks read-first, then write.
- `requestAnimationFrame`, scroll events, and ordinary effects are not automatically layout-clean.
- `scrollIntoView` performs synchronous visibility/scroll calculation. An explicit low-frequency reveal may still be correct and cheaper than changing interaction timing.
- Replacing `scrollIntoView` with `offsetTop`, rect reads, or computed style does not inherently remove forced layout.
- Distinguish **natural layout work**