debugging

Debugging

Feedback Loop FIRST: No hypothesis without a repro loop. No fix without root cause. No fix without blast radius scan.

Reference Files

• references/investigation-hygiene.md — investigation discipline, evidence handling
• references/root-cause-playbooks.md — scenario-specific debugging playbooks

Feedback Loop FIRST (Before Any Hypothesis)

A hypothesis without a repro loop is a guess. Before H1, build a fast, deterministic, agent-runnable signal that turns red on the bug.

Construction Ladder (try in rank order, stop at first that works — ordered by loop tightness: earlier rungs are faster and more deterministic)

1. Failing automated test (unit/integration) — best: lives at a seam, reusable as RED
2. curl/HTTP request with asserted response
3. CLI snapshot diff (run command, diff stdout/stderr/exit)
4. Headless browser script (real DOM/runtime crash)
5. Trace replay (recorded request/log/event re-run)
6. Throwaway harness (tiny script calling the suspect function)
7. Property/fuzz check (when failing input is unknown)
8. git bisect run (regression with existing test)
9. Differential old-vs-new (last-good vs HEAD behavior diff)
10. Human-in-the-loop (LAST resort: scripted manual steps)

Tighten the loop — treat it as a product. Once you have a loop, keep tightening:

• Faster? Cache setup, skip unrelated init, narrow the test scope — sub-second beats sub-minute.
• Sharper signal? Assert the exact failing fact, not a noisy superset — never just "didn't crash".
• More deterministic? Pin time, seed RNG, isolate filesystem, freeze network — same input → same red, no drift. A 30-second flaky loop is barely better than none; a 2-second deterministic one is a debugging superpower.

Red-capable completion criteria — the loop is done when you can name one command (a script path, a test invocation, a curl) that you have already run at least once (paste the invocation and its output), and it is:

• Red-capable — drives the actual bug code path and asserts the user's exact symptom (can go red on this bug, green once fixed). Not "runs without erroring".
• Deterministic — same verdict every run (flaky bugs: a pinned, high reproduction rate).
• Fast — seconds, not minutes.
• Agent-runnable — you can run it unattended. No red-capable command, no hypothesis phase. If you catch yourself reading code to build a theory before this command exists, STOP.