Agent Debug Troubleshooter 1

Stop watching your AI agent edit the same file 6 times without fixing anything. Diagnose the failure pattern and apply the right recovery technique in minutes.

The Problem

Your AI agent has edited src/parser.py 4 times, each time introducing a different syntax error while trying to fix the original one. It's now 11 PM, you've burned 45 minutes on what should have been a 5-minute fix, and the agent keeps saying "I've fixed it!" while the test still fails. You suspect the agent is stuck in a loop, but you don't know why — is it missing context? Did it hallucinate a dependency? Is it compensating for an earlier mistake without backtracking? You need a diagnostic framework, not more retries.

What You Get

• 5 failure pattern classifications — Edit Loop (repeated edits to same file, same error), Instruction Decay (early turns follow instructions, later turns get sloppy), Hallucinated Dependency (references non-existent functions/modules), Cascade Failure (one error leads to increasingly wrong corrections), and Context Drift (gradually shifting focus from original goal)
• Divergence point detection — step-by-step protocol to identify the exact tool call where the agent's approach started failing, by comparing the last reasonable tool call against the first deviant one
• Pattern-specific recovery techniques — Edit Loop: "Stop editing. Read the entire file and test file. Explain the gap in one sentence before editing." Instruction Decay: "CRITICAL: Remember [constraint] is still in effect." Hallucinated Dependency: "Check if [function] exists before using it." Cascade Failure: "Undo last 3 tool calls. Restart from [known good state]." Context Drift: "Read the user's first message again."
• Escalation protocol — structured report for the user after 3 failed recovery attempts, listing the agent's tool call sequence, the diagnosed failure pattern, and what was tried
• Recovery verification — post-recovery checklist confirming the test passes, the agent can explain why the previous approach failed, and no new errors were introduced

Why This Beats Prompting It Yourself

When an agent is stuck, the natural human response is to say "try again" or "fix it differently" — which often pushes the agent deeper into the failure loop. This skill provides a structured triage protocol: pause → classify → apply specific recovery → verify. Each failure pattern has a different root cause and requires a different technique. "Try again" is not a technique — it's a gamble.

Example Session

You: My agent has edited src/auth.py 5 times and the tests still fail. Help.

Agent: Classification: Edit Loop — agent edited the same function validate_token() 5 times, each time changing the error message but not fixing the underlying validation logic. The error persists because the agent is treating the symptom (wrong return value) not the cause (missing JWT expiry check).

Recovery: Stop editing src/auth.py. Read the ENTIRE file. Then read the test file tests/test_auth.py::test_expired_token. Identify what the test expects that the implementation doesn't provide. Do not edit until you can explain the gap in one sentence.

Agent response: "The test expects validate_token() to return {"valid": False, "reason": "expired"} for tokens with exp < now(), but the current implementation only checks iss and sub claims — it never validates the exp claim."

Fix applied: Added exp claim validation with datetime.utcnow().timestamp() > payload["exp"] check. Test passes. Recovery successful in 1 attempt.

Use Cases

• Diagnosing why an AI agent is stuck in a repetitive edit loop on a specific file
• Recovering from instruction decay in long coding sessions (50+ turns) where the agent starts ignoring early constraints
• Identifying hallucinated API calls that reference non-existent library functions
• Backtracking from a cascade of compensating edits that made the code worse with each attempt
• Realigning an agent that drifted from the original task scope during a complex multi-file refactor

Known Limitations

The classification system works best when the agent's tool call history is visible (Claude Code, Cursor with conversation logs). If the agent is running in a mode where tool calls are not logged, divergence point detection requires manual observation. Some failure patterns overlap — an edit loop caused by hallucinated dependencies may look like a simple edit loop until the root cause is identified.

---

Tags: debugging troubleshooting ai-agents agent-observability developer-tools

Version: 1.0.0