| name | auto-performance |
| version | 0.1.0 |
| disable-model-invocation | true |
| user-invocable | true |
| description | Make code measurably faster without breaking it: metric + reproducible baseline FIRST, profile to the real hotspots, then per hotspot apply a change and re-benchmark — kept ONLY if the win is real beyond variance AND correctness holds; otherwise reverted. Stops at the target or diminishing returns. Never accepts an unmeasured "should be faster".
|
| allowed-tools | ["Bash","Read","Edit","Write","Grep","Glob","Agent","Workflow"] |
| effort | high |
| argument-hint | [target — endpoint/function/page/metric, or a perf budget] (default: profile to find it) |
| arguments | ["target"] |
| when_to_use | Use when there's a performance requirement or a suspected regression and you want to optimize the RIGHT
thing, proven by measurement. Do NOT use to add features, fix functional bugs (auto-build), or do
behavior-neutral readability cleanups (auto-simplify); and do NOT "optimize" without a benchmark — an
unmeasured change is a guess, and guesses here routinely make things slower or wronger.
|
Optimization without measurement is superstition, and optimization that breaks correctness is a
regression. Non-negotiable:
1. MEASURE FIRST. Establish the metric + a reproducible baseline benchmark BEFORE any change. No baseline
→ no optimization; you can't improve what you haven't measured.
2. PROFILE, DON'T GUESS. Target the hotspots the profiler shows, not the ones intuition suggests. Most
guessed bottlenecks aren't; optimizing a non-hotspot adds complexity for no gain.
3. BENCHMARK-GATED ACCEPT. Keep a change ONLY if a re-benchmark shows a REAL improvement (beyond
run-to-run variance, apples-to-apples: same input, same warm/cold state). "Looks faster" / "should be
faster" is never acceptance — REVERT anything unproven.
4. NO CORRECTNESS REGRESSION. Every kept optimization must pass the full relevant test suite AND an
adversarial regression check (edge cases the speedup might have changed). A faster wrong answer is a
bug, not a win.
5. STOP AT DIMINISHING RETURNS. When the target is met, or the remaining gains are small relative to the
complexity they cost, STOP — don't keep trading readability for microseconds.
6. FAIL CLOSED. Report real measured deltas. Never claim an improvement you didn't measure.
Auto Performance
Overview
Turn "make it faster" into a disciplined, measured loop: define the metric, baseline it, profile to the
real hotspots, and improve them one at a time — each improvement earning its place with a before/after
number and a clean correctness check, or getting reverted. The measurement gate is the whole point: it's
what separates real optimization from complexity-adding cargo-culting.
Phase 0: Define the metric and baseline it (measure first)
- Pin the METRIC to the target: latency (p50/p95/p99), throughput, memory/allocations, bundle size, or a
web vital (LCP/CLS/INP) — with a numeric target if one exists (from the spec or a budget).
- Build a REPRODUCIBLE benchmark for it: fixed input, controlled warm/cold state, enough iterations to see
past variance. Record the baseline (with its variance/spread — a single number isn't enough).
- Open a
checkpoint-resume run.
Success criteria: a metric, a numeric target (or "reduce X"), and a reproducible baseline with known
variance.
Phase 1: Profile to the real hotspots
- Run a profiler / measurement appropriate to the stack (CPU/alloc profiler, query logs, flame graph,
bundle analyzer, DevTools performance trace). Identify where the time/memory actually goes.
- Rank hotspots by contribution to the metric. Ignore cold paths — optimizing them is wasted complexity.
- For each hotspot, note the likely class (algorithmic complexity, N+1/roundtrips, needless allocation,
blocking I/O, re-render/re-compute, oversized payload).
Success criteria: a ranked list of the hotspots that actually move the metric, each with a suspected
cause.
Phase 2: Optimize one hotspot, prove it (converge, benchmark-gated)
Run converge-loop toward the target; per hotspot (highest-impact first):
- Hypothesize the change and the expected effect on the metric.
- Apply the smallest optimization that tests the hypothesis.
- Re-benchmark and verify (
adversarial-verify, two lenses):
- measurement lens — is the delta real (beyond variance, apples-to-apples)? or noise / a broken
benchmark?
- regression lens — does the full relevant test suite still pass? does any edge case now behave
differently (the classic "optimized the happy path, broke the boundary")?
- Accept or revert — keep ONLY if the improvement is real AND correctness holds. Otherwise revert and
record why (no gain / regressed / not worth the complexity). Update the checkpoint.
Exit when the target is met, or when the remaining hotspots offer gains too small to justify their
complexity cost.
Success criteria: each kept change has a measured before/after and a clean correctness check; unproven
changes are reverted.
Phase 3: Report
Close the checkpoint and report: baseline → final metric (with the real delta and variance), the
optimizations kept (each with its measured gain), the ones tried-and-reverted (why), and whether the
target was met or where it stalled and why.
Success criteria: an honest, measured account — no claimed gain lacks a number.
Common Rationalizations
| Rationalization | Reality |
|---|
| "This is obviously the bottleneck, optimize it." | Obvious bottlenecks are usually wrong. Profile — optimizing a non-hotspot adds complexity for zero gain. |
| "It should be faster now, ship it." | "Should be" isn't measured. Re-benchmark; if the delta isn't real (beyond variance), revert. |
| "It's a bit faster and the tests pass, good enough." | A tiny gain that costs real readability/complexity may be a net loss. Weigh the gain against the complexity; stop at diminishing returns. |
| "The happy path is faster." | And did an edge case break? A faster wrong answer is a regression. Run the regression lens. |
| "Micro-optimize every function." | Cold-path micro-opts add complexity with no metric impact. Optimize hotspots only. |
| "One benchmark run showed improvement." | One run is noise. Use enough iterations and compare against variance before believing the delta. |
Red Flags
- A change accepted with no before/after measurement.
- Optimizing code the profiler didn't flag as hot.
- A benchmark that isn't apples-to-apples (different input, warm vs cold, changed between runs).
- Correctness tests not re-run after an optimization (or a subtle edge-case behavior change ignored).
- Claimed speedups within run-to-run variance.
- Complexity piled on for sub-threshold gains past the target.
Guardrails
- Never optimize without a baseline; never accept a change without a re-benchmark showing a real delta.
- Never optimize a non-hotspot; profile first.
- Never keep an optimization that regresses correctness; revert on any behavioral change.
- Never claim an unmeasured improvement.
- Stop at the target / diminishing returns — don't trade clarity for noise-level gains.
When To Load References
converge-loop (skill) — the optimize-toward-target loop with termination + anti-thrash.adversarial-verify (skill) — the measurement + regression lenses that gate each accept.checkpoint-resume (skill) — durable perf-run state.auto-test (skill) — ensure a correctness safety net exists before optimizing under-covered code.
Output Contract
Report:
- metric + target; baseline (with variance) → final (with the real delta)
- optimizations kept — each with its measured gain and the hotspot it addressed
- optimizations tried and reverted — with why (no gain / noise / regression / not worth complexity)
- target met, or where it stalled and the reason
