Debugging with an agent: reproduce first, or you're just editing code

The signature is the same in every row: the change lands where the symptom surfaced, not where the state went wrong. In my bug, the symptom surfaces inside humanize(), which is the one function in the file that is behaving correctly. A guard there makes node bin/report.js print a clean report — and leaves isLive() answering true for an expired session, which is an auth decision, not a formatting one. One of the pressure runs said this out loud in its summary, unprompted, while shipping a one-line fix:

"The same skip bug means isLive could have reported an expired session as live, since it shares pruneExpired. […] if anything downstream made an auth or access decision off isLive while this was in production, it was answering true for expired sessions whenever two expired ones sat adjacent in the array."

That is the sentence you are trying to obtain from a debugging session. It is not "I fixed it" — it is a claim about the blast radius of the mechanism, and it is checkable. So the first thing to read in any bug-fix diff is not whether the change is correct but where it is. If the fix sits at the throw site, ask why the state was wrong before it got there. That question costs one turn and is the single highest-yield thing you can say in a debugging session.

The loop that works

Four steps in a fixed order, with one hard gate in the middle.

1. Reproduce. One command, deterministic, failing. If the bug needs state — a row in a table, an expired token, a specific clock — the reproduction is the thing that manufactures that state, not a description of it. This step is done when the agent has pasted output it obtained by running something, not output it predicted.

2. Narrow. From the failing command down to the smallest call that still produces the bad state. The instruction that does the work here is a distinction: find the line that produces the wrong value, not the line that throws. Without it, the search terminates at the stack trace, which is a report of where the program noticed, not where it went wrong.

3. State the mechanism — before any edit. Two sentences: which line produces the wrong state, and why. This is the gate, and its ordering is the point. An explanation written before the change is a prediction you can check. The same words written after are a rationalisation of a diff that already exists, and models are extremely good at producing those. You are also, at this exact moment, the cheapest reviewer in the loop: you read two sentences and decide whether they are a mechanism or a vibe. "There was a race condition" is a vibe. "The loop index advances past the element that shifted into the vacated slot" is a mechanism — it predicts which inputs fail and which don't, so you can test it.

4. Change, then verify against step 1. One edit, then the original failing command passing. If the change is bigger than the mechanism warrants, that gap is where the next bug will be introduced.

You do not need a framework for this. The whole protocol fits in a prompt, and it is the exact text I used for arm B:

node bin/report.js crashes with "Error: negative TTL: -1800000".

Work in this order and do not skip a step:
1. Reproduce it. Run the command and paste the exact output.
2. Narrow it. Find the smallest call that produces the bad state —
   not the line that throws, the line that produces the value that throws.
3. State the mechanism in two sentences before you edit anything:
   which line produces the wrong state, and why.
   Do not edit any file before this step.
4. Write a failing test that captures the mechanism, not the crash
   message, and show it failing.
5. Only then fix it, and show the test passing.

If you use this often, it belongs in a slash command or a skill rather than your clipboard. And keep it short: a debugging protocol that has grown to forty lines is competing for attention with the actual bug, which is a bad trade in a window that is already filling up with file reads.

The failing test is the contract

Step 4 is the one people skip, and it is the one that gives the word "fixed" a definition. Without it, "fixed" means "the thing I was looking at stopped happening", which is satisfied by every row in the suppression table above.

The rule that makes the test worth writing: assert the mechanism, not the message. Watch how differently these two fail. A test written against the symptom —

test('report does not throw', () => {
  assert.doesNotThrow(() => summary(sessions, NOW))
})

— passes the moment anyone wraps the call in a try, or softens the humanize guard, or deletes the invariant. It is satisfied by the bug being hidden. A test written against the mechanism cannot be:

test('pruneExpired drops adjacent expired sessions', () => {
  const sessions = [
    { id: 'a', expiresAt: NOW + 600_000 },
    { id: 'b', expiresAt: NOW - 60_000 },
    { id: 'c', expiresAt: NOW - 1_800_000 },
    { id: 'd', expiresAt: NOW + 600_000 },
  ]
  assert.deepEqual(pruneExpired(sessions, NOW).map((s) => s.id), ['a', 'd'])
})

That is a real test from one of the protocol runs, and the shape is what matters: it names the input class that triggers the mechanism — adjacent expired entries — rather than the string the crash happened to print. It fails on the old code for the right reason, and no guard, catch, or tolerance can make it pass.

There is a sequencing detail worth insisting on. Make the agent show the test failing before it writes the fix. A test authored after the fix has never been observed to fail, which means you have no evidence it can. It is common — and completely silent — for such a test to assert something the code did before the fix as well.

What an agent is genuinely better at than you

None of the above is a claim that you should debug and the agent should type. There is a real division of labour here, and it is not the one people assume.

Notice what these have in common: each is a search with a checkable result. The agent is doing work whose output you can verify cheaply — a list, a commit hash, a set of call sites. That is the category where delegating is close to free.

What it is worse at — and it is one thing

Everything that needs state you have and it does not.

• The flaky CI job. The failure lives in a container you are not in, with a different clock, different parallelism, and a different filesystem. An agent asked to fix flakiness from the repo alone will reliably propose a plausible cause — test ordering, a shared fixture, a timing assumption — and it will be plausible whether or not it is true.
• The race. Reproduction is the entire problem, and it is stubbornly local: your machine's core count, your event loop, your lock contention. The mechanism is a claim about interleaving, which is exactly the claim a model can construct fluently without evidence.
• The production-only failure. Data shape, scale, a config value, a version skew, a customer with 40,000 rows where your fixture has three. The bug is in the difference between environments, and the agent can only see one of them.
• "It worked yesterday." The information is in the interval, not the code — deploys, migrations, a dependency that moved, a certificate that expired.

The move in all four cases is the same, and it is not "debug it yourself". It is bring the state to the agent, so the thing it lacks stops being missing. Paste the failing CI run's full log rather than describing it. Give it the git log for the interval instead of saying "recently". Hand it the production row that breaks, anonymised. Ask it to write the script that reproduces the race under load — building reproductions is a coding task, which is the thing it is good at, rather than a debugging task, which is the thing it is guessing at.

And when the state genuinely cannot be transported, say so in the prompt and constrain the output to match: "You cannot reproduce this. Do not change any code. Rank the candidate mechanisms and tell me what evidence would separate them." An agent asked for hypotheses gives you a list you can test. The same agent asked for a fix gives you a diff you cannot evaluate — and the diff will look exactly as confident as the list would have been useful.

When to stop and read the code yourself

The honest rule has three triggers, and they all detect the same underlying condition — the agent has stopped reasoning from evidence and started iterating on plausibility.

1. Two failed fixes in a row. Not two rounds of refinement — two changes that were supposed to resolve it and did not. After the second, the window contains two wrong theories that are still shaping every subsequent token, and the third attempt is drawn toward them. Start a new session with what you learned, or read the code.
2. The diff is growing while the symptom stays. Defensive checks accumulating around a failure is the visible form of guessing. A correct diagnosis usually makes the change smaller: nine of my twelve runs replaced seven lines with one, and the three under time pressure fixed it with a single added i--.
3. You cannot restate the mechanism in your own words. This is the one that catches the dangerous case, because it fires while everything still looks fine. If the explanation reads well and you could not defend it to a colleague, you do not have a diagnosis — you have prose. Ask for the mechanism again in one sentence, with the specific input that triggers it. If the second answer is not the same as the first, the agent is generating explanations rather than recalling one.

"Read it yourself" is also not the only fallback. For a bug where being wrong is expensive, putting the mechanism in front of a second, independently trained model is cheap and catches the case where one model's plausible story is another's obvious error — the same second-reviewer argument that applies to diffs applies to diagnoses, and diagnoses are where a single confident narrator is most dangerous.

The short version

• A bug prompt without a reproduction is a request for a guess. Give the command, the output, and the input — or say plainly that you cannot, and make building one step one.
• Make the agent state the mechanism before it edits. Before is a prediction; after is a rationalisation.
• Read where the diff landed, not just what it says. A change at the throw site is the signature of symptom suppression.
• Write the failing test against the mechanism, not the message — and make it fail before the fix exists.
• Delegate the searches: unfamiliar stacks, bisects, call-site sweeps, logs.
• Don't delegate the state you hold. Transport it instead — logs, git ranges, real rows, a reproduction script.
• Stop after two failed fixes, when the diff grows without the symptom shrinking, or when you cannot restate the explanation.
• And do not assume the failure mode you fear is the one you have. On my twelve runs it never fired. Measure your own.

Where Backgrind fits

Nothing above needs a product — it is a prompt, a test, and the discipline to read a diff before approving it. But debugging this way has a side-effect worth naming: it produces a lot of waiting. Reproduce, narrow, explain, test, fix is five stops where the agent needs something from you, and the honest way to work while an agent bisects a repository is to do something else and be interrupted when it finishes.

That is the part Backgrind handles. It runs your real CLI in an always-on-top overlay with a tab per session and a background daemon that keeps them alive when the window is hidden, so the bisect you started can grind away while you work the other branch — and the tab that needs a decision pings with an accent ring and a chime instead of sitting silently at a prompt. Twelve headless runs is a fine way to gather data; one attended session per bug is how you actually ship. See the loop in the live demo.

Frequently asked questions

Sources

Everything numeric in this post comes from runs I performed on 7 August 2026, not from published benchmarks. Setup: a five-file Node repo (ESM, node:test, no dependencies) containing one off-by-one bug — Array.prototype.splice called inside a forward for loop — plus a four-test suite that passes on the buggy code because every test prunes a single expired entry. Twelve runs of claude -p on Claude Code 2.1.223, default model, reported by the run JSON as claude-opus-5[1m]; each run used --permission-mode acceptEdits with Bash, Edit, Write, Read, Glob and Grep allowed, and a fresh copy of the repo. Four arms of three runs (bare, reproduce-first protocol, no-reproduction-available, time pressure), prompts quoted verbatim in the table above. Scoring: a held-out three-assertion test file, never present during any run, copied in afterwards; "ran the code before first edit" was derived from the ordered tool-call stream (--output-format stream-json) by checking whether any Bash call before the first Edit or Write actually executed the module. Turn counts and dollar costs are the num_turns and total_cost_usd fields of each run's result event; the total was $5.77. The user-level CLAUDE.md on this machine was in scope for every run and contains no debugging instructions; there was no project CLAUDE.md. Twelve runs against one bug in one language is an anecdote with a denominator, not a benchmark — in particular it says nothing about mechanisms that are not well-known patterns, which is exactly where I would expect an unreproduced fix to fail. The taxonomy of symptom-suppressing fixes is drawn from practice, not from these runs: none of the twelve produced one.