Watch an agent debug something and you'll see the failure mode almost immediately: it reads the stack trace, forms a theory in about one second, and starts editing code. If that fix doesn't work, it forms a second theory and edits again. By the third attempt it's not debugging anymore — it's pattern-matching on what usually fixes things that look like this, which is a different activity wearing the same name.
Debugging is a search problem. Guessing is the slowest search algorithm there is, because every wrong guess costs a full edit-test cycle and teaches you nothing you can reuse for the next guess. The fix isn't a smarter agent — it's a procedure the agent isn't allowed to skip, with the skip conditions named explicitly so "this one's obvious" doesn't count as an exception.
The procedure
1. Reproduce. Make the failure happen on demand, in the smallest case you can construct. A bug you can't reproduce is a bug you can't verify you fixed — you'll ship a change and find out weeks later whether it actually worked.
Gate: no hypotheses, no fixes, no code changes until this step is done. This is the rule that matters most and the one that gets skipped most, because reproduction feels like overhead when the cause "obviously" is X.
2. Capture the evidence. Exact error text, stack trace, failing input, expected vs. actual — written down before touching anything. The crime scene degrades as soon as you start changing state to test theories.
3. Isolate. Shrink the search space by bisection: halve the input, the commit range, the config, or the code path, and re-test. Repeat until the trigger is pinned to one variable. This is the step that turns "somewhere in this 400-line file" into "this one conditional."
4. Hypothesize — one at a time. State the suspected cause as a sentence that could be false. Design the cheapest test that would falsify it. Run it. Record the verdict before forming the next hypothesis. The discipline is sequential, not parallel — an agent (or a person) juggling three theories at once loses track of which evidence supports which.
5. Fix at the root. Fix the cause, not the symptom. If the fix lands in a different place than the error appeared, that's normal — just say why in one sentence, because that sentence is what a reviewer needs to trust the diff.
6. Prove it. The reproduction from step 1 now passes. The rest of the test suite still passes. Where practical, the reproduction becomes a permanent regression test — otherwise you've fixed this instance and left the trap armed for the next person.
7. Log the lesson. One paragraph — root cause, fix, and the class of bug — appended to the PR description or the project's debugging notes. This is the step that compounds: six months of these paragraphs is a searchable map of every way your codebase has actually broken.
The red flags worth hardcoding
These are the exact sentences that precede a wrong fix, and they're specific enough to catch in the moment:
- "The cause is obvious, I'll just fix it." (Then reproduction takes 30 seconds and costs nothing — so do it anyway.)
- "I can't reproduce it, but this fix should cover it."
- "Let me try changing this and see what happens." (That's a hypothesis. State it and test it properly instead of editing blind.)
- Editing code while the reproduction is still unwritten.
- Third fix attempt for the same symptom — this one specifically means the bug isn't where you think it is, and the answer is to go back to step 3, not to try a fourth guess.
If you're writing this into an agent's instructions rather than following it yourself, that last one is worth a hard stop: after two failed fix attempts on the same symptom, block further edits until reproduction and isolation are redone.
When reproduction is genuinely impossible
Intermittent, production-only failures exist, and the procedure has to adapt rather than dissolve when reproduction fails: instrument (add the logging you wish you already had), narrow the trigger statistically instead of deterministically, and ship the fix behind evidence that it addresses the only remaining suspect — labeled explicitly as a probabilistic fix, never reported as "fixed." An agent that reports a guess as a confirmed fix has produced a worse outcome than one that says "I couldn't reproduce this, here's my best evidence-backed guess and what I'd watch for next."
None of this needs special tooling — it's a checklist you can paste into any agent's instructions or a code review template. This is the exact, unedited procedure from the free Agent Starter Kit's systematic-debugging skill, published in full (no signup) at the link above if you want the ready-to-use file with the YAML frontmatter that makes an agent load it automatically.
Top comments (0)