Profile Optimizer

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:

| Format | Extension | Detection signal | | -------------------------- | ------------------------ | ----------------------------------------------------------------- | | React DevTools Profiler | .json (often .reactprofile) | Top-level keys include dataForRoots and rendererID / version | | Chrome Performance trace | .json / .json.gz | Top-level traceEvents array (or NDJSON with ph, ts, cat) | | Chrome CPU profile (legacy)| .cpuprofile | Top-level nodes, samples, timeDeltas | | Chrome heap snapshot | .heapsnapshot | Top-level snapshot.meta.node_fields + nodes/edges/strings | | Chrome heap timeline | .heaptimeline | Heap snapshot shape + samples array | | Chrome heap profile (sampled allocations) | .heapprofile | Top-level head + samples (V8 sampling-allocation profile) |

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](./rules/input-detection.md) for the precise detection logic.

---

Workflow

Six phases. Do not skip a gate.

| Phase | Name | Rule file | Gate | | ----- | ------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | 0 | Intake | [rules/input-detection.md](./rules/input-detection.md) | Format detected, file size and validity confirmed | | 1 | Measurement frame | [rules/measurement-methodology.md](./rules/measurement-methodology.md) | Baseline metric chosen (TBT, INP, p95 commit, retained MB, etc.) and target stated | | 2 | Hotspot extraction | [rules/react-profile-analysis.md](./rules/react-profile-analysis.md), [rules/chrome-trace-analysis.md](./rules/chrome-trace-analysis.md), or [rules/heap-snapshot-analysis.md](./rules/heap-snapshot-analysis.md) | Top-N bottlenecks listed with concrete numbers (ms / MB / %, count) | | 3 | Root-cause | [rules/optimization-playbook.md](./rules/optimization-playbook.md) | Each hotspot mapped to a code-level cause (file path / component / API) | | 4 | Confidence gate | [rules/confidence-loop.md](./rules/confidence-loop.md) | /confidence analysis ≥ 90% — else iterate (max 2 deep-dives) | | 5 | Optimisation plan | [templates/analysis-report.md](./templates/analysis-report.md) | Report written with ranked fixes, expected impact, and verification plan |

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.

| Phase | Files | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | [rules/input-detection.md](./rules/input-detection.md) | | 1 | [rules/measurement-methodology.md](./rules/measurement-methodology.md) | | 2 (CPU) | [rules/react-profile-analysis.md](./rules/react-profile-analysis.md), [rules/chrome-trace-analysis.md](./rules/chrome-trace-analysis.md) | | 2 (Memory) | [rules/heap-snapshot-analysis.md](./rules/heap-snapshot-analysis.md) (also points to [scripts/heap-summary.mjs](./scripts/heap-summary.mjs) and [scripts/heap-diff.mjs](./scripts/heap-diff.mjs)) | | 3 | [rules/optimization-playbook.md](./rules/optimization-playbook.md), [references/react-optimization-patterns.md](./references/react-optimization-patterns.md), [references/chrome-optimization-patterns.md](./references/chrome-optimization-patterns.md) | | 4 | [rules/confidence-loop.md](./rules/confidence-loop.md) | | 5 | [templates/analysis-report.md](./templates/analysis-report.md) |

---

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:

| Score | Action | | ------------ | --------------------------------------------------------------------------------------------------- | | ≥ 90% | Proceed to Phase 5 (optimisation plan). | | 70–89% | Run one deeper pass: re-read the profile, look at the next-deepest frame, correlate sources. | | **` rendered 47 times in a 230ms commit, accounting for 38% of that commit" is.

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

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

1. Auto-detect, do not interrogate. Read the file, infer the format,

state what you found. Ask the user only if detection genuinely fails.

1. Confidence-gated honesty. If /confidence returns /scripts/heap-summary.mjs

```

1. Run heap-diff for the leak case to find what grew between two

snapshots: ``bash node --max-old-space-size=4096 \ /scripts/heap-diff.mjs ``

1. Map suspects to source. Use [rules/heap-snapshot-analysis.md](./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](./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](./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).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mthines
• Source: mthines/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.