debug-loop

debug-loop — no theory before a red loop

Goal: the bug is fixed, a test that once went red on it now passes, and the cause that turned out to be true is on the record.

Redact before you show anything: commands, outputs and captured logs often carry credentials. Write <REDACTED> in their place and keep secrets in environment variables.

1. Build a feedback loop that goes red on this bug

This is the whole skill; everything after it is mechanical. Spend disproportionate effort here, and be inventive. Roughly in order of preference:

1. a failing test at whatever seam reaches the bug;
2. a request script against a running server;
3. a command run on a fixture, its output diffed against a known-good one;
4. a headless browser script asserting on the page, console or network;
5. a captured payload or trace replayed through the code path;
6. a throwaway harness that runs just the failing path;
7. a loop over many random inputs, for "sometimes wrong";
8. a bisection script between a known-good and a known-bad state;
9. the same input through the old and new versions, outputs diffed;
10. as a last resort, a scripted checklist a human follows, each result fed back to you.

Then tighten it: faster (skip unrelated setup), sharper (assert the exact symptom, not "did not crash"), steadier (pin time, seed randomness, isolate the filesystem). For an intermittent bug, raise the reproduction rate until it is debuggable — loop it, parallelise it, add load.

Done when you can name one command, already run and shown with its output, that drives the real code path, asserts the user's exact symptom, gives the same verdict every run, finishes in seconds and runs without a human. Until that command exists, the next step is more loop-building, not reading code for a theory.

If you genuinely cannot build one, say so and list what you tried. Mark the task blocked with that list as the reason, and ask the user for access to an environment that reproduces it, a captured artifact, or permission to add temporary instrumentation.