Debugging when the agent goes in circles
Recognise a poisoned session, restart cleanly, supply evidence instead of opinions, and reduce the problem until it is obvious.
Recognising the loop
| Symptom | What is happening | Response |
|---|---|---|
| Same fix attempted twice | The session is anchored to a wrong cause | Start a fresh session |
| Increasingly large edits | It is guessing and widening the blast radius | Revert and re-scope |
| Confident explanation, no evidence | It is narrating a plausible story | Demand the failing output |
| Reads the same files repeatedly | Context pressure | Clear and restate |
| Adds tests that pass immediately | Testing the code it wrote, not the behaviour | Write the check yourself |
| Blames the environment | Unknown cause | Reproduce by hand first |
The important insight is that a long session accumulates a narrative. Once the agent has explained a cause to itself and built on that explanation, it defends the explanation rather than testing it. Clearing the conversation is not a defeat - it is removing a wrong assumption that is no longer visible.
The clean restart
- Revert to the last known good commit. Debugging on top of failed attempts hides the original behaviour.
- Reproduce the failure by hand and capture the exact command and output.
- Start a new session. Paste the command, the output, the file paths and the constraint on what not to change.
- Ask for a diagnosis with evidence before any edit.
- Require the smallest change that tests the diagnosis.
"Fresh task. Do not assume anything from a previous attempt.
Reproduce: npm test -- cart.test.ts
Actual:
Expected: 200
Received: 500
TypeError: Cannot read properties of undefined (reading 'total')
at src/cart/total.ts:14
Files: src/cart/total.ts, src/cart/build.ts
Constraint: the test is correct. Do not change it.
First, read src/cart/total.ts and tell me what you think line 14 receives
and why, with the evidence from the code. Do not edit yet."⚠️
Pasting your theory into the prompt is the most common way to poison a fresh session. State the observation and let the agent form the hypothesis; if you supply the cause, you get agreement rather than investigation.
Reduce to a minimal reproduction
# the failing case, isolated, outside the app
mkdir /tmp/repro && cd /tmp/repro && npm init -y
npm i <the-one-library>
node repro.mjs
# the failing test, narrowed
npx vitest run -t "rejects a redeemed code"
npx playwright test cart.spec.ts --grep "stock"- A fifty-line reproduction that still fails is worth more than any amount of discussion about the codebase.
- Bisect with git: find the commit that introduced the failure, then read only that diff.
- Delete everything not required to reproduce. The bug is usually in what remains.
- Once it reproduces in isolation, the fix is usually obvious to you before it is to the agent.
- Keep the reproduction as a regression test, so this failure cannot return.
git bisect start
git bisect bad HEAD
git bisect good v1.4.0
git bisect run npm test -- cart.test.ts
git bisect resetFAQ
How do I know when to give up on a session?
After two failed corrections of the same defect, or as soon as you notice the agent re-reading files it has already read. Both indicate the session's context is working against you, and a clean restart with the evidence is faster than a third attempt.
The agent says it fixed it but nothing changed. Why?
Usually the change was made in a different file, or the process is serving a stale build, or a generated artefact was edited instead of the source. Check the diff, restart the dev server, and confirm you are editing the file the running code actually loads.
Related
Reviewing generated code like an owner The generate, run, correct loop
Last refreshed 2026-09-18.