Perf Hunt

---
name: perf-hunt
description: >
  Find and land real performance wins with measured proof. Use when the user
  says "perf hunt", "find performance wins", "make it faster", "why is this
  slow", "reduce bundle size", "optimize", or runs /theo-mode perf. Requires
  building a measurement harness first; guesses are not wins.
---

# Perf Hunt

Goal: measurable speedups, proven with before/after numbers, landed as
separate commits. Hard cuts are allowed. Speculation is not.

## Step 0: you need a ruler before you cut

Do not touch code until you can measure it. Find or build ONE of:

- An existing benchmark script (`bench/`, `scripts/perf*`, `vitest bench`,
  `go test -bench`, `cargo bench`, `pytest-benchmark`).
- A repeatable timing command: `hyperfine 'node dist/cli.js ...'`, `time`, a
  curl loop against a local server, a Lighthouse or bundle-size check.
- A profile: `node --cpu-prof`, `py-spy`, `perf`, `pprof`, Chrome DevTools
  trace via `chromium-cli`.

If none exists, write a small one into `scripts/bench/` and commit it. That
script is part of the deliverable. Future agents need it too.

Run the baseline three times. Record median and spread in `NOTES.md`. If the
spread is wider than the win you are about to claim, the measurement is
useless. Fix the measurement first.

## Step 1: find the fat

Look in the places where wins are usually hiding:

- **N+1 and repeated work.** Queries or fetches inside loops. The same
  expensive computation done on every call instead of once.
- **Hot-path allocations.** Array spreads, object copies, regex compiles, JSON
  round-trips inside loops or per-request handlers.
- **Startup cost.** Importing the whole library to use one function. Sync file
  reads at module load. Big barrel files.
- **Bundle size.** `moment` where `Date` would do. Icon packs imported whole.
  Polyfills for browsers nobody uses.
- **Wrong data structure.** `array.includes` in a loop where a `Set` fits.
  Linear scans over something that should be indexed.
- **Waiting serially.** `await` in a loop where `Promise.all` is safe.

Use the profile to rank them. Attack the top item, not the easiest one.

## Step 2: cut, measure, commit, repeat

For each change:

1. Make the change. Keep it small enough to explain in one sentence.
2. Run the benchmark three times. Record median.
3. If the win is real (outside the noise band), commit with the numbers in
   the message: `perf: dedupe user fetch in list route (p50 412ms -> 88ms)`.
4. If the win is not real, revert. Do not keep "cleaner" code that did not get
   faster. That is a refactor, not a perf win.
5. Run the test suite before moving on. A fast wrong answer is a regression.

## Step 3: report

One table: change, before, after, delta, commit hash. Then one line on what
you measured with and how to re-run it. Then the next three candidates you did
not get to, ranked.

## Cost guardrail

Benchmarks and profiles are expensive to run and expensive to read. Cap
yourself at ~5 landed wins per session unless told otherwise. Stop when the
remaining candidates are under 5% each.