diagnosing-bugs

name	diagnosing-bugs
description	Run the diagnosis loop for hard bugs, failing behavior, regressions, thrown errors, or slow paths.
metadata	{"internal":true}

diagnosing-bugs

A discipline for hard bugs. Build a tight loop that goes red on this bug FIRST; everything after is mechanical. Doctrine + the fleet adaptations: diagnosing-bugs.md. Skip a phase only with an explicit reason.

Phase 1 — Build the loop

Construct one named, agent-runnable command that drives the bug code path and asserts the user's exact symptom — a failing pnpm test <file>, a CLI+snapshot diff, an httpJson script, a trace replay, a bisection/differential loop. Never a throwaway harness you delete after.

Make it tight: fast (seconds), deterministic (pin time, seed RNG, freeze the network with nock), sharp (asserts the symptom, not "didn't crash"). For a flaky bug, raise the reproduction rate until it's debuggable.

Completion criterion: you can paste one command you have already run and its output, and it is red-capable, deterministic, fast, and agent-runnable. If you catch yourself reading code to build a theory before this command exists — stop. No red-capable command, no Phase 3.

If you genuinely cannot build a loop, say so explicitly, list what you tried, and ask for environment access / a captured artifact. Do not proceed to hypothesise.

Phase 2 — Reproduce + minimise

Run the loop; watch it go red on the user's symptom (not a nearby one). Then shrink the repro: cut inputs, callers, config one at a time, re-running after each, until every remaining element is load-bearing. Don't proceed until reproduced AND minimised.

Phase 3 — Hypothesise

Generate 3–5 ranked falsifiable hypotheses before testing any — each states a prediction ("if X is the cause, changing Y makes it disappear"). No prediction = a vibe; sharpen or discard. Show the ranked list to the user before testing (cheap checkpoint; they may re-rank instantly) — but proceed on your ranking if they're AFK.

Phase 4 — Instrument

One variable per probe, mapped to a specific Phase-3 prediction. Prefer a debugger/REPL over logs. Tag every debug log [DEBUG-<hex>] so cleanup is one grep — never "log everything and grep". Perf bugs: measure a baseline first (performance.now(), profiler, query plan), then bisect.

Phase 5 — Fix + regression test

Write the test before the fix, but only at a correct seam — one that exercises the real bug pattern at the call site. Fleet seam doctrine: public interface, highest available seam, vitest in test/ (members co-locate; wheelhouse hook/lint-rule tests in test/repo/), never node:test, never source-text assertions. Turn the minimised repro into a failing test, watch it fail, apply the fix, watch it pass. If no correct seam exists, that is the finding — flag it.

Phase 6 — Cleanup + post-mortem

grep out the [DEBUG- tags, run pnpm run check + pnpm test, commit with the root cause named in the message (fix(<scope>): <root cause>). If this is the second occurrence of the same shape, search the repo for siblings before closing (variant analysis).