Troubleshooting
When the feedback loop breaks — common failure modes and what to do.
Most failures are broken feedback loops — either the agent isn't getting signals, or it's ignoring them.
The session is going off the rails
Symptom: Looping, unrelated changes, contradicting earlier decisions.
Why: Context window drift. The window is full of dead ends and stale error messages; the signal-to-noise ratio keeps dropping.
Fix: Stop. Write down what you learned, revise the plan, and start a fresh session with a clean context. A compromised context window is not recoverable. Starting fresh is always cheaper than you think.
The agent claims success without verification
Symptom: "It works!" with no test output, no screenshot. Or "tests pass" with no test output in the transcript.
Why: LLMs are trained to be agreeable. Confidence is the default; verification is extra work the agent will skip if you let it.
Fix: Demand the artifact — test output, typecheck exit code, dev server response, screenshot. If the agent can't produce it, the task isn't done. Better: wire verification into a PostToolUse hook so it runs automatically on every edit.
Fix A breaks B, fix for B breaks C
Symptom: Each fix introduces a new failure elsewhere. You're losing ground.
Why: Fixing symptoms, not the root cause. Each fix moves the contradiction somewhere else.
Fix: Revert all attempted fixes. Return to the oldest failing state and ask "what assumption am I violating here?" If the root isn't obvious, use /grill-me or start fresh.
The agent is working from bad information
Symptom: Hallucinated APIs, imports to wrong packages, deprecated signatures. Or "the build is failing" followed by guesses that miss.
Why: Pattern-matching from training data instead of verifying against the actual codebase. Or the agent saw a generic failure message and is filling in blanks.
Fix:
- Enable strict TypeScript — most hallucinations fail the type check
- Require the agent to read the actual file before using anything from it
- For library APIs, fetch current docs via MCP rather than trusting memory
- Give it the logs directly — pipe build output, make errors copy-pasteable, add a unified check script
When in doubt
- Throw away the session and restart with a revised plan. 90% of stuck sessions are a context-window problem in disguise.
- Break the task smaller. If it was too big for one session, split it into pieces that each fit cleanly.