diagnosing-bugs — feedback loop first, then hunt

The move that makes debugging mechanical: get a fast, deterministic pass/fail signal before you theorise. Reading code before you have a red-capable loop is the failure this prevents. (Distilled in our own way from Matt Pocock's diagnosing-bugs, MIT.)

1. Build a feedback loop (spend the most effort here)

A command that runs the bug's code path and asserts the exact symptom. Prefer, in order: a failing test at the bug's seam → an HTTP/curl script → a CLI + fixture + snapshot → a headless-browser script → replay a captured trace → a throwaway harness → a property/fuzz loop → a bisection harness → an old-vs-new differential loop.

• Tighten it like a product: fast (aim ~2s, not 30s flaky), sharp (assert the specific symptom, not "didn't crash"), deterministic (pin time, seed RNG, isolate FS/network).
• Flaky bug? Raise the reproduction rate (loop 100×, parallelize, add stress) — a 50% flake is debuggable, 1% isn't.
• Can't build a loop? STOP. List what you tried and ask the user for access to a reproducing env, a captured artifact (HAR / log / core dump), or permission to instrument. Never hypothesise without a loop.

2. Reproduce + minimise

Run the loop; confirm it's the user's exact symptom, not a nearby failure. Then shrink to the smallest scenario that still fails — cut inputs/callers/config/steps one at a time, re-running after each. Done when every remaining element is load-bearing. (The minimal repro becomes your regression test.)

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." Can't state the prediction? Discard it. Show the ranked list to the user (they have context) before probing.

4. Instrument (one variable at a time)

Each probe maps to one prediction. Prefer a debugger/REPL breakpoint (one beats ten logs) over logging; never "log everything and grep." Tag every debug log with a unique prefix ([DEBUG-a4f2]) so cleanup can grep-and-remove them. Performance regressions: logs lie — establish a baseline measurement (profiler / performance.now() / query plan), then bisect. Measure first, fix second.