Debugging with an agent instead of a print statement

Print-statement debugging works by narrowing: you suspect a region, instrument it, and follow the values. It is effective when you already know roughly where the problem is.

It fails on the bugs where you do not — where the cause is three files away from the symptom, or where the code is correct and the assumption behind it is not. Those are the ones that consume days.

An agent is well suited to that class, because it can read the whole path from symptom to cause without holding it in working memory. But it only helps if you describe the problem in a way that makes the search tractable, and most bug reports do the opposite.

Expected. What should happen, specifically. Not 'it should work'.

Actual. What happens instead, with the exact error text if there is one. Paraphrased errors send the search in the wrong direction.

Reproduction. The shortest sequence that triggers it, including the input. 'Sometimes when I save' is not reproducible; 'when the file has no trailing newline' is.

Ruled out. What you have already checked and eliminated. This is the one that gets left out, and it is the most valuable — without it the agent re-treads your ground, confirms what you already knew, and you both lose twenty minutes.

'Fix this error' invites the shortest change that makes the error stop. Often that is a guard clause around the symptom, which works and leaves the actual defect in place to reappear elsewhere.

Ask instead: find the cause, explain it, and propose a fix — in that order, and stop before applying it. You want the explanation, because you are the one who can judge whether it is the real cause or a plausible story.

Find why this happens. Explain the mechanism before
suggesting a change. Do not edit anything yet.

The pause is doing real work. An explanation you can evaluate is the difference between debugging and delegation.

An agent will produce a coherent explanation whether or not it is correct, and coherent explanations are persuasive. The defence is to test rather than to trust.

Two useful questions. 'What is the smallest test that would confirm this?' — then run it. And 'if this diagnosis is wrong, what else could produce the same symptom?' — which surfaces alternatives that were being suppressed by the first plausible answer.

When a proposed cause cannot be confirmed by a concrete test, treat it as a hypothesis rather than a finding, however well argued it is.

Timing and concurrency. Race conditions do not reproduce reliably and reading the code rarely reveals them. An agent will find plausible-looking suspects that are not the cause.

Environment. A bug that exists on one machine and not another is usually not in the code at all. Establish that it reproduces cleanly before starting a code search.

Wrong requirements. When the code does exactly what it was asked and the asking was wrong, no amount of reading finds a defect, because there is not one.

All three share a tell: the search keeps returning correct-looking code. If nothing is wrong with the code, the problem is not in the code.

Once the cause is confirmed and fixed, ask for a test that would have caught it. This is where an agent is genuinely fast, and it is the step most often skipped under time pressure.

Then ask whether the same mistake appears elsewhere. Bugs of this kind are usually a pattern rather than an incident — the same wrong assumption applied in three places by the same person on the same afternoon.

Those two questions take a minute and frequently produce more value than the original fix.