Profile Optimizer

Turn a profile file into a ranked, evidence-backed optimisation plan.

Index file. Detailed analysis rules, optimisation patterns, and report templates live under rules/, references/, and templates/. Load only what the current phase needs — the body of SKILL.md is a thin orchestrator.

Inputs

The user passes one or more profile files. Accept any of:

If the file is gzipped, decompress with gunzip -k before parsing.

If multiple formats are passed, treat them as complementary evidence:

• React profile + Chrome trace → correlate by wall-clock timestamp (React shows component cost, Chrome shows where the main thread actually spent time).
• Two or three heap snapshots → diff them to find what grew (leak detection).
• Chrome trace + heap timeline of the same interaction → CPU + memory cost of one action correlated.

See rules/input-detection.md for the precise detection logic.

Workflow

Six phases. Do not skip a gate.

Phases 2 and 3 branch on the input format (CPU / memory) — everything else is shared.

Required reading by phase

Load on demand — do not preload.

Confidence-gated iteration

After the first pass at root-cause analysis, invoke the confidence skill in analysis mode:

Skill(skill="confidence", args="analysis")

Apply this gate:

After two deep-dive iterations without reaching 90%, stop and present findings as a hypothesis with the evidence required to confirm it. This is the /confidence iteration protocol applied to performance work — see rules/confidence-loop.md.

Core principles

1. Measure before recommending. Every fix must be tied to a number from the profile. "This component re-renders too much" is not a finding; "<UserList> rendered 47 times in a 230ms commit, accounting for 38% of that commit" is.
2. Rank by impact, not by ease. A 5ms fix on a hot path beats a 50ms fix on a cold one. Use the profile's own data to estimate ceiling impact.
3. Root cause over symptom. A long task is the symptom; the work inside it is the cause. Do not stop at "task X took 240ms" — drill into the call stack.
4. Auto-detect, do not interrogate. Read the file, infer the format, state what you found. Ask the user only if detection genuinely fails.
5. Confidence-gated honesty. If /confidence returns < 90%, dig deeper or admit uncertainty. Do not paper over a weak diagnosis with a confident-sounding fix.
6. One profile at a time, but correlate when given two. A React profile plus a matching Chrome trace is far more powerful than either alone.

Anti-patterns (one-liners — full list in

rules/optimization-playbook.md)

• Recommending useMemo/useCallback everywhere without measuring (the React Compiler exists, and unmeasured memoisation often regresses).
• Treating a long task in Function call as the root cause without expanding the call stack.
• Reporting raw event counts without converting to percentage of total blocking time or commit duration.
• Skipping the confidence gate because the first hypothesis "looks right".
• Fixing one big bottleneck and ignoring the long tail of repeated small ones (death-by-a-thousand-cuts is the common case in real apps).

Memory-profiling quickstart

When the input is a heap snapshot / timeline / profile:

1. Validate capture. A single snapshot is only good for a baseline analysis — refuse to diagnose a leak from one. Leak diagnosis needs ≥ 2 snapshots, ideally 3 (baseline → after-action → after-cleanup).
2. Run heap-summary on the most recent snapshot for top constructors and node-type breakdown:

   node --max-old-space-size=4096 \
     <skill_dir>/scripts/heap-summary.mjs <snapshot.heapsnapshot>

3. Run heap-diff for the leak case to find what grew between two snapshots:

   node --max-old-space-size=4096 \
     <skill_dir>/scripts/heap-diff.mjs <before.heapsnapshot> <after.heapsnapshot>

4. Map suspects to source. Use rules/heap-snapshot-analysis.md Phases 3–4 to go from constructor name → source file → retainer pattern.

The full methodology (capture protocol, how to interpret the diff, common leak shapes) is in rules/heap-snapshot-analysis.md. Don't preload it — only when an input is detected as a heap format.

Definition of Done

• Input format detected and stated.
• Baseline metric and target chosen (Phase 1) — ms for CPU work, MB retained for memory work.
• Top-N hotspots listed with measured cost (ms / MB / %, count).
• Each hotspot mapped to a file/component/API/constructor with line or retainer references where possible.
• /confidence analysis reached ≥ 90% (or two deep-dives recorded with the remaining uncertainty surfaced to the user).
• Optimisation plan written using templates/analysis-report.md, with ranked fixes, expected ms / MB saved, and a re-profile verification step.
• User has the next concrete action (apply fix N, re-profile, compare).