Agent Debug Loop (Introspection)
Overview
Systematic self-debugging for AI agent failures. Captures state before retrying blindly, diagnoses against known failure patterns, applies contained recovery actions, and produces a structured human-readable report. This is a workflow skill, not a hidden runtime—it teaches the agent to debug itself before escalating to a human.
When to Use
Trigger phrases:
- "agent loop", "agent stuck", "agent failing", "debug agent"
- "tool call limit", "context overflow", "repeated retries"
Use directly when:
- Maximum tool-call / loop-limit failures reached.
- Repeated retries produce no forward progress.
- Context growth or prompt drift degrades output quality.
- File-system or environment state mismatches expectations.
- Tool failures are likely recoverable via diagnosis + smaller corrective action.
When NOT to Use
- Feature verification after code changes → use
test-agent or verification-loop pattern.
- Framework-specific bugs where a narrower skill already exists.
- Runtime promises the current harness cannot enforce automatically.
Anti-Rationalization Table
| Rationalization |
Reality |
| "I'll just retry the same approach harder." |
Blind retries burn tokens and worsen context pressure. Capture state first, then change one variable. |
| "The tool must be broken." |
Most tool failures are state mismatches (wrong cwd, stale file hash, missing dependency), not tool bugs. Verify assumptions before blaming the tool. |
| "I can keep everything in memory and figure it out." |
Agents have no persistent memory across compaction. Write the failure capture to disk (local:// or artifact) so recovery survives context loss. |
| "One more attempt will fix it." |
If two identical attempts failed, the third will too. Switch strategy or escalate. |
Workflow
Phase 1: Failure Capture
Before recovering, record the failure precisely:
## Failure Capture
- Session / task:
- Goal in progress:
- Error type + message:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Context pressure indicators (loop count, token estimate):
- Environment assumptions to verify:
Persist this to local://agent-failure-capture.md or an artifact so it survives compaction.
Phase 2: Root-Cause Diagnosis
Match the failure to a known pattern:
| Pattern |
Symptom |
Likely Cause |
| Stale anchor |
Edit tool hash mismatch |
File changed since last read; re-read before editing |
| Path confusion |
ENOENT on existing file |
Wrong cwd, symlink, or relative-path assumption |
| Dependency gap |
Import/module error |
Missing install, virtualenv, or PATH entry |
| Context bloat |
Degraded reasoning, repetition |
Oversized pasted logs, duplicated plans, runaway notes |
| Tool misuse |
Invalid arguments |
Misread schema; re-check tool docs |
| State race |
Intermittent pass/fail |
Concurrent writer, unlocked shared file |
| Loop lock |
Same 3 steps repeat |
No exit condition; plan lacks termination check |
Verify each assumption empirically—run one diagnostic command per hypothesis rather than guessing.
Phase 3: Contained Recovery
Apply the smallest corrective action that breaks the pattern:
- Reset context: Trim oversized notes; drop duplicated plans.
- Re-anchor state: Fresh
read of target files; confirm cwd and branch.
- Reduce scope: Split the failing step into two smaller verifiable sub-steps.
- Switch strategy: Different tool, different approach, or delegate to a subagent with clean context.
- Escalate cleanly: If two recovery attempts fail, stop and hand off with the capture report attached.
Phase 4: Introspection Report
Produce a structured report:
## Agent Introspection Report
- Failure class: [pattern from Phase 2]
- Evidence: [commands run + outputs]
- Recovery applied: [what changed]
- Outcome: [resolved / still blocked]
- Prevention: [rule or checklist item to avoid recurrence]
Verification
1---2name: agent-debug-loop3description: Use when an agent run fails repeatedly, consumes tokens without progress, loops on the same tools, or drifts away from the intended task. Structured self-debugging workflow using capture, diagnosis, contained recovery, and introspection reports.4domain: agents5subdomain: orchestration6category: agents7version: 1.0.08author: oyi779license: Apache-2.010tags:11- debugging12- agent-harness13- context-management14- loop-detection15- self-improvement16triggers:17- agent loop18- agent stuck19- agent failing20- debug agent21- tool call limit22- context overflow23argument-hint: "[failure description]"24metadata:25 source: https://skillmd.com/skills/oyi77/agent-debug-loop26---2728# Agent Debug Loop (Introspection)2930## Overview3132Systematic self-debugging for AI agent failures. Captures state before retrying blindly, diagnoses against known failure patterns, applies contained recovery actions, and produces a structured human-readable report. This is a workflow skill, not a hidden runtime—it teaches the agent to debug itself before escalating to a human.3334## When to Use3536**Trigger phrases:**37- "agent loop", "agent stuck", "agent failing", "debug agent"38- "tool call limit", "context overflow", "repeated retries"3940Use directly when:41- Maximum tool-call / loop-limit failures reached.42- Repeated retries produce no forward progress.43- Context growth or prompt drift degrades output quality.44- File-system or environment state mismatches expectations.45- Tool failures are likely recoverable via diagnosis + smaller corrective action.4647## When NOT to Use4849- Feature verification after code changes → use `test-agent` or `verification-loop` pattern.50- Framework-specific bugs where a narrower skill already exists.51- Runtime promises the current harness cannot enforce automatically.5253## Anti-Rationalization Table5455| Rationalization | Reality |56|---|---|57| "I'll just retry the same approach harder." | Blind retries burn tokens and worsen context pressure. Capture state first, then change one variable. |58| "The tool must be broken." | Most tool failures are state mismatches (wrong cwd, stale file hash, missing dependency), not tool bugs. Verify assumptions before blaming the tool. |59| "I can keep everything in memory and figure it out." | Agents have no persistent memory across compaction. Write the failure capture to disk (`local://` or artifact) so recovery survives context loss. |60| "One more attempt will fix it." | If two identical attempts failed, the third will too. Switch strategy or escalate. |6162## Workflow6364### Phase 1: Failure Capture6566Before recovering, record the failure precisely:6768```markdown69## Failure Capture70- Session / task:71- Goal in progress:72- Error type + message:73- Last successful step:74- Last failed tool / command:75- Repeated pattern seen:76- Context pressure indicators (loop count, token estimate):77- Environment assumptions to verify:78```7980Persist this to `local://agent-failure-capture.md` or an artifact so it survives compaction.8182### Phase 2: Root-Cause Diagnosis8384Match the failure to a known pattern:8586| Pattern | Symptom | Likely Cause |87|---|---|---|88| **Stale anchor** | Edit tool hash mismatch | File changed since last read; re-read before editing |89| **Path confusion** | ENOENT on existing file | Wrong cwd, symlink, or relative-path assumption |90| **Dependency gap** | Import/module error | Missing install, virtualenv, or PATH entry |91| **Context bloat** | Degraded reasoning, repetition | Oversized pasted logs, duplicated plans, runaway notes |92| **Tool misuse** | Invalid arguments | Misread schema; re-check tool docs |93| **State race** | Intermittent pass/fail | Concurrent writer, unlocked shared file |94| **Loop lock** | Same 3 steps repeat | No exit condition; plan lacks termination check |9596Verify each assumption empirically—run one diagnostic command per hypothesis rather than guessing.9798### Phase 3: Contained Recovery99100Apply the smallest corrective action that breaks the pattern:1011021. **Reset context**: Trim oversized notes; drop duplicated plans.1032. **Re-anchor state**: Fresh `read` of target files; confirm cwd and branch.1043. **Reduce scope**: Split the failing step into two smaller verifiable sub-steps.1054. **Switch strategy**: Different tool, different approach, or delegate to a subagent with clean context.1065. **Escalate cleanly**: If two recovery attempts fail, stop and hand off with the capture report attached.107108### Phase 4: Introspection Report109110Produce a structured report:111112```markdown113## Agent Introspection Report114- Failure class: [pattern from Phase 2]115- Evidence: [commands run + outputs]116- Recovery applied: [what changed]117- Outcome: [resolved / still blocked]118- Prevention: [rule or checklist item to avoid recurrence]119```120121## Verification122123- [ ] Failure captured to persistent artifact before any retry124- [ ] Root cause matched to a known pattern with evidence125- [ ] Exactly one variable changed per recovery attempt126- [ ] Escalation triggered after two failed recovery attempts127- [ ] Prevention rule recorded (via `learn` or managed-skill update)