# Nuke Perf

> Use when something is slow, expensive, or claimed to need optimization — "nuke perf", "why is this slow", "optimize this", "make it faster" — and the change must be proven by measurement, not narrated. No optimization without a baseline number; no success claim without before/after from the same harness.

- Skill: `b4r7x/nuke-perf` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add b4r7x/nuke-perf`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/nuke-perf/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: b4r7x (https://skillmd.com/u/b4r7x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b4r7x/nuke-perf

---


# Nuke Perf

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

1. **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.
2. **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.
3. **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.
4. **One change at a time.** Each fix cycle lands one hypothesis's minimal change; a combined diff that improved things proves nothing about why.
5. **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.
6. **No `git add` / `git commit` / `git stash`. No `.bak` files.** Working tree left for review.
7. **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 — <baseline> → <after> (<Δ%>), N runs, harness: <command>. 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.