nuke-debug's sibling for speed (map: references/family-map.md — a self-contained loop). The cheap-model failure mode it corrects: "optimizing" by idiom — sprinkling caches, memoization, and Promise.all on cold paths — and claiming victory without a number. The iron law mirrors debug's: no optimization without a measurement, and the fix phase is unreachable until a baseline exists. A perf claim without before/after numbers from the same harness is a guess wearing a diff.
Arguments
[mode] — light (default) | full | plan (preflight, print, STOP).
<target> — the slow thing: a command, endpoint, test, function, or user-visible symptom ("cold start takes 9s").
--ask — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md).
Modes
Tier vocabulary and platform mechanics: references/model-tiers.md.
| light (default) | full | |
|---|---|---|
| Profiler | worker | worker |
| Hypothesis agents per wave | 2 · worker | 3 · session |
| Adjudicator — loads nuke-think when installed | session | top |
| Fixer | worker | worker |
| Validator (re-measure) — one tier above the fixer | session | top |
| Hypothesis-wave cap | 2 | 3 |
| Fix → re-measure cycle cap | 3 | 5 |
Mandates
- NO OPTIMIZATION WITHOUT A MEASUREMENT. Phase 3 is unreachable until Phase 1 produces a reproducible baseline number with the harness recorded. Unmeasurable target after honest effort → STOP and report what instrumentation is missing.
- Same harness, same conditions, both sides. Before and after run the identical command, inputs, and environment; warm-up runs and run counts stated. Numbers are pasted verbatim, never summarized.
- Hot path or no path. A change to code the profile shows cold is rejected by the validator regardless of how idiomatic the optimization looks. Micro-tuning without a measured hot spot is a finding, not a fix.
- One change at a time. Each fix cycle lands one hypothesis's minimal change; a combined diff that improved things proves nothing about why.
- Behavior is preserved. The matching gates (references/stack-adapters.md) pass after every change; a fast wrong answer is a regression, and the validator treats it as one.
- No
git add/git commit/git stash. No.bakfiles. Working tree left for review. - Never claim success past a dirty state. Cap hit → the verdict is the honest cycle log with numbers, not "should be faster now".
Artifacts
run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-perf-<slug>/ — fresh per run; on collision append -2, -3, ….
| File | Role |
|---|---|
plan.md |
Target, harness, baseline command, scope, gates, tiers |
perf.md |
Baseline numbers, profile, hypotheses with verdicts, per-cycle before/after, final table |
Pipeline
Phase 0 preflight → Phase 1 baseline + profile → Phase 2 hypotheses (waves, cap 2/3) → Phase 3 fix (one change) → Phase 4 re-measure + gates → verdict
│ unmeasurable → STOP: report missing instrumentation │ no survivor → STOP: report eliminations
Phase 0 — Preflight
Read references/preflight.md and follow its plan-then-apply gate. Perf specifics: resolve the target into a runnable measurement — an existing bench script, a timed test, a repeatable command with timing, or a profiler invocation; state runs and warm-ups. Resolve the gates table for the touched prefixes (references/stack-adapters.md). A measurement or gate command that cannot run at all follows the unblock protocol in references/preflight.md. Print the plan block and apply it (gate only with --ask).
Phase 1 — Baseline + profile (worker)
Run the measurement N times (N in the plan; ≥3 for wall-clock); record every number verbatim plus variance. High variance → find the stabilizing condition (fixed input, disabled network, pinned seed) before proceeding — a baseline that swings 40% localizes nothing. Then profile with the stack's tooling and the hot-spot vocabulary of references/stack-adapters.md table C; the profile output (top functions/queries/allocations) goes into perf.md verbatim.
Phase 2 — Hypotheses
Waves of hypothesis agents with assigned stances — algorithmic (wrong complexity, redundant recomputation) / io-concurrency (blocking calls, N+1, missing parallelism) / allocation-memory (churn, unbounded growth, GC pressure) — each must tie its claim to a quoted profile line and name the expected gain and the minimal change. Every claim labeled fact or assumption. The adjudicator (loads nuke-think when installed) picks by evidence quality; a hypothesis whose cost the profile does not show is rejected on the spot (Mandate 3). No survivor after the wave cap → STOP, report eliminations honestly.
Phase 3 — Fix (worker)
One fixer, one hypothesis, the smallest diff that removes the measured cost (Mandate 4). Mandatory skill loading per the plan's file-type → skill map. No drive-by refactors; no speculative caching beyond the hypothesis.
Phase 4 — Re-measure + gates (validator)
A fresh validator — never the fixer — re-runs the identical harness (Mandate 2), pastes before/after side by side, runs the matching gates (Mandate 5), and verdicts: improved (gain quantified, gates green) · no effect (change reverted, hypothesis marked cleared, next hypothesis or next wave) · regression (reverted, recorded). Improvement that plateaus below the target → next hypothesis, counting against the cycle cap.
Verdict
- "FASTER — → (<Δ%>), N runs, harness: . Gates green, working tree ready for review (nothing committed)."
- NOT MEASURABLE — what instrumentation is missing.
- NOT LOCALIZED — waves used, hypotheses eliminated with evidence.
- NOT IMPROVED — cycles used, every change reverted, the numbers that refused to move.
Always: the final before/after table, profile evidence, run stats; calibration line appended to .nuke/calibration.log (format in references/preflight.md). Systemic findings (an architecture that cannot be fast) → recommend nuke-audit on the area.