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:

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

3. Run the bundled bounded-memory summarizer:

   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:

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:

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:

   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:

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 from synchronously forced scheduling. Observer-driven code may coalesce layout without eliminating the layout itself.
• Do not claim “whole page/tree layout” without trace scope, layout-object evidence, or containment analysis.

Recognize root-cause families

• Reducer recreates every entity when derived values are unchanged.
• Memoized child receives fresh callbacks, arrays, objects, or context projections.
• Selector scans/sorts all entities once per consumer, producing O(S × (T + I)) work.
• Streaming or resize commits trigger unconditional scroll-container geometry reads.
• A measurement effect reads, writes state/style, then causes another render/layout pass.
• The same resize is covered by both ResizeObserver and a global resize listener.
• Virtualizer DOM writes are followed by parent scroll geometry reads in the same commit.
• Development profiling, extensions, or source-map instrumentation dominate the apparent frame.

Fix the earliest owner. Do not hide producer churn with broad leaf memoization or replace a proven geometry problem with timing heuristics.

Choose a fix without semantic drift

Data and render churn

• Reuse references when every rendered/derived value is exactly equal.
• Stabilize event-time callbacks without freezing stale reads.
• Replace repeated scans with one-pass grouping while preserving filters, orphan rules, stable ordering, and tie-breakers.
• Keep exact comparators in named helpers.
• Avoid persistent indexes unless evidence proves ephemeral grouping insufficient.