Give an agent a stack trace and a vague "fix this" and watch what happens: it reads the error, forms a theory in about four seconds, and starts editing code. If that's wrong — and it usually is on anything non-trivial — it forms a second theory just as fast, edits more code, and now you're three plausible-looking diffs deep with no idea which one, if any, actually addressed the bug.
That's not a model capability problem. It's what happens when nothing forces the agent to be systematic. Left unprompted, agents debug like a junior engineer at 2am: guess, patch, hope, repeat. The fix isn't a smarter model — it's encoding the discipline explicitly, as a set of gates the agent can't skip past.
The four-step discipline
1. Force reproduction first. The hard gate: no fix proposals until the failure reproduces in a minimal, isolated case. This is the single highest-leverage rule and the one agents skip most eagerly, because proposing a fix feels like progress and reproducing a bug feels like stalling. It isn't. A fix for a bug you haven't reproduced is a guess wearing a diff's clothing.
In practice this means telling the agent explicitly: strip the failing case down to the smallest input/config that still triggers it, and show you that minimal case failing, before touching any source file. If it can't reproduce, the next step is narrowing the repro conditions — not writing code.
2. Isolate with bisection. Once it reproduces, have the agent binary-search for the trigger — across commits (git bisect), across inputs, across config flags. Bisection turns "somewhere in these 40 commits" into "this exact commit" in log₂(40) ≈ 6 steps instead of a linear scan. Agents are actually very good at mechanical bisection once told to do it; they're bad at deciding to do it unprompted.
3. One falsifiable hypothesis at a time. Not "it's probably a race condition, let me add a fix" — a specific claim that a specific test can prove wrong: "the callback fires before the listener attaches; adding a log line before and after both should show the ordering." Run it. If the hypothesis survives, act on it. If it doesn't, the agent should log what it ruled out and form the next one — not quietly pivot to a new theory while treating the first as if it never happened.
4. Write the post-mortem before closing the loop. The agent appends root cause and fix to a debugging journal — a plain file in the repo, not a mental note that evaporates when the session ends. This is the step that compounds: without it, the same class of bug gets rediscovered from scratch next month by an agent (or a person) with zero memory of the first time.
Why this actually changes behavior
None of these four steps require a better model. They require refusing to let the agent skip ahead. The gate in step 1 is the load-bearing one — everything downstream depends on it, because a hypothesis tested against a bug that isn't actually reproducing yet is a hypothesis tested against nothing.
If you're writing this as a skill or system prompt rather than repeating it by hand every time, the gate needs to be phrased as a blocking condition, not a suggestion — "do not propose a fix" reads very differently to an agent than "try to reproduce first if you can." Agents follow explicit gates far more reliably than they follow tone.
The post-mortem step is the one people skip because it feels like overhead after the bug is already fixed. It's the one that pays for itself the third time the same class of bug shows up and the agent reads its own notes instead of re-deriving the fix from scratch.
Full playbook: https://agentkitworks.com/use-cases/debug-with-agents
Top comments (0)