| name | agent-introspection-debugging |
| description | Structured 4-phase self-debug for failing agent runs (looping, drifting, burning tokens). Capture, diagnose, contained recovery, report. Complements /investigate (which is for code bugs); this skill is for harness/agent failures. |
| allowed-tools | ["Bash","Read","Grep","Glob","AskUserQuestion"] |
/agent-introspection-debugging — Self-Debug for Failing Agent Runs
Adapted from affaan-m/everything-claude-code/skills/agent-introspection-debugging.
This is the harness/agent failure companion to /investigate (DOTS-specific code bugs). When the failing thing is the agent itself — looping, drifting, burning tokens without progress — use this skill to debug the agent before debugging the code.
When to use
- An agent run hits its retry budget (e.g.,
/build-fix 4-attempt limit)
- A subagent (
/deep-review, feature-builder, codex-rescue) reports failures with no useful output
- Multiple consecutive tool calls return errors with no forward progress
- Context growth or drift is degrading output quality (e.g., responses become repetitive, instructions ignored)
- File-system or environment state mismatch between expectation and reality
- Tool failures that look likely-recoverable with a smaller corrective action
When NOT to use
- For DOTS code bugs (Harmony failures, GameModel misbehavior, etc.) → use
/investigate
- For build errors that the retry budget hasn't yet exhausted → use
/build-fix
- For verifying completed work → use
/deep-review
- When you don't actually know what's failing → first surface the symptoms via plain investigation, then invoke this skill once you have specifics
Four-Phase Loop
Phase 1: Failure Capture
Before retrying anything, record the failure precisely. Most agent failures are made worse by re-running blind — the second attempt has the same context as the first plus a wasted run.
Capture:
| Item | Why |
|---|
| What was the agent attempting? (one sentence) | Frames everything else |
| What went wrong? (exact error, last useful tool result, last meaningful agent output) | Distinguishes "tool error" from "model drift" |
| What had the agent done in the N tool calls before failure? (high level, not full transcript) | Catches context exhaustion / loop patterns |
| What did the agent output OR plan to output that didn't make sense? | Catches drift before re-running re-derives the same wrong plan |
| Token usage / context % (if visible from status line) | Distinguishes "out of room" from "stuck on logic" |
Output of Phase 1: a single paragraph plus the literal failure string. Don't skip — Phase 2 needs it.
Phase 2: Diagnose Against Known Patterns
Match the captured failure against this checklist before forming a new hypothesis:
| Pattern | Signature | Recovery |
|---|
| Retry-budget exhaustion | Same error text repeating across 3+ attempts | The fix isn't in the local file — escalate to /investigate for root cause, or to user |
| Stale-file mismatch | Edit tool returns "string not found" but the string is visibly there | Re-Read the file (per csharp-architecture.md stale-file rule); something modified it since the last Read |
| Context exhaustion | Output becomes truncated, repetitive, or skips instructions | /compact or invoke /context-save then start a fresh session |
| Tool not found / env failure | command not found, permission denied, path does not exist | Per environment-failures.md: report, don't fix — escalate to user |
| Subagent loop | A spawned agent returned an output that triggers another spawn of the same agent | Stop spawning. Address whatever the agent's output asks for in the parent context. |
| Inline-hook block | Edit blocked by [freeze] deny message | The freeze boundary is doing its job; either widen scope (/freeze again with broader path), /unfreeze, or accept that this edit is out of scope |
| MCP server unhealthy | MCP tool calls timeout or return MCP-level errors | Check mcp-health-check.sh log; the hook will block calls to flagged servers for 60s. Wait or invoke a different tool. |
| Permission prompt loop | User keeps being asked the same permission | Add the action to .claude/settings.local.json allowlist via /update-config |
| Hallucinated tool / API | Agent calls a tool name or API that doesn't exist | Tool typo OR agent confused about available tools. Stop, list available tools, invoke correctly. |
| Plan drift | Agent's stated plan doesn't match what it's doing | Re-state the original task explicitly; if the agent rejects it, hand control back to user |
If the failure matches a pattern, jump to Phase 3 with the corresponding recovery. If no pattern matches, proceed to Phase 3 with a fresh hypothesis.
Phase 3: Contained Recovery
Apply the smallest corrective action. Do not retry the original failing action with the same context — that's the loop trap.
Bias toward:
- Smaller scope — if the agent failed on 5 files, retry on 1
- Fresh context — if context exhausted, save state then start clean (
/context-save → new session → /context-restore)
- Different tool — if Edit failed, try Write. If Bash failed, try a smaller scoped command. If Glob failed, try Grep.
- Human in the loop — if 3 hypotheses fail, stop and surface to user with full Phase 1+2 output. The cost of a 30-second user clarification is much less than a fourth wrong attempt.
The recovery action MUST be something genuinely different from the original failing attempt — not a slight rewording of the same approach.
Phase 4: Introspection Report
Whether the recovery succeeded or escalated to user, output a structured debug report:
AGENT INTROSPECTION REPORT
====================================
Original task: [what the agent was trying to do]
Failure mode: [from Phase 2's table, or "novel pattern: <description>"]
Captured signal: [the literal error or output that surfaced the failure]
Recovery taken: [the contained action from Phase 3]
Outcome: RECOVERED | ESCALATED_TO_USER | STILL_BLOCKED
Cost saved: [rough estimate: how many wrong-direction tool calls would have happened without this introspection]
Pattern to add: [if Phase 2 had no matching pattern, propose what to add to the table]
====================================
If the failure mode was novel and recurring is plausible, propose adding it to:
- This SKILL.md's Phase 2 table (most patterns)
.claude/rules/harness-facts.md (if it's a load-semantic / lifecycle finding)feedback_*.md memory entry (if it's a DOTS-specific lesson)
Pair with
/investigate — for code bugs; this skill is for agent/harness bugs. The boundary is: if a fresh agent in a fresh session would hit the same problem, it's a code bug → /investigate. If only THIS agent's drift causes it, it's an agent failure → THIS skill./freeze / /unfreeze — Phase 3 recoveries that scope-lock or release/context-save / /context-restore — Phase 3 recoveries for context exhaustion/compact — same/codex-rescue — when the in-session agent can't recover, hand off to Codex (out-of-band, fresh context)
Notes
- This skill is read-only by design. It does NOT make code changes — recoveries either re-attempt with smaller scope or escalate.
- The Phase 2 table is the most important asset; extend it whenever you encounter a novel pattern. The table loses value if it becomes stale.
- Don't run this skill recursively — if introspection itself is failing, escalate immediately to the user.
