---
name: agent-introspection-debugging
version: 1.0.0
description: |
  Structured self-debugging for an agent that is stuck, looping, or failing
  repeatedly. Replaces blind re-prompting with capture -> diagnose -> contained
  recovery -> report. Use when the same step fails twice, a loop is not making
  progress, tool calls keep erroring, or you are about to retry without a new
  hypothesis.
---

# Agent Introspection Debugging

When an agent is stuck, the instinct is to try again harder. That burns tokens
and usually reproduces the failure. This is a workflow, not a hidden runtime:
it forces you to name the failure, classify it, take the smallest action that
changes the diagnosis, and report honestly  -  before retrying.

## When to use

- The same step failed twice, or a fix loop is not converging.
- Tool calls keep erroring (connection refused, rate limit, stale state).
- You are about to retry with no new hypothesis  -  the signal to stop and think.

## Phase 1 - Capture

Write the failure state down before acting:

- Goal (what were you actually trying to do).
- The exact error or wrong output.
- Last successful step, and the first failing step.
- What is repeating (same error? different each time?).
- Environment assumptions (cwd, branch, service up, auth present).

## Phase 2 - Diagnose

Match the symptom to a cause before choosing an action:

| Symptom | Likely cause | First check |
| --- | --- | --- |
| Hit max tool calls / no end | unbounded loop | is there a stop condition? |
| Context overflow | unbounded notes/output | what is being accumulated? |
| Connection refused | service/port down | is it running, right port? |
| Rate limited (429) | retry storm | back off, not retry faster |
| Diff/state looks stale | cwd or branch drift | pwd, current branch |
| Tests still failing after "fix" | wrong hypothesis | re-read the actual assertion |

## Phase 3 - Contained recovery

Take the single smallest action that changes the diagnosis surface  -  not a
broad rewrite. Change one variable, re-observe. The goal is new information,
not a gamble on a fix.

**Honesty guard:** do not claim recovery actions you are not actually
performing. "Reset agent state," "cleared the cache," "restarted the service"
are real only if you did them through a real tool. Narrating an imaginary
auto-heal is worse than reporting that you are blocked.

## Phase 4 - Introspection report

Emit a short structured record:

- Root cause (the confirmed one, not the first guess).
- Result: `success` | `partial` | `blocked`.
- Cost: rough tokens/time burned on the failure.
- Preventive change: the rule, check, or guard that would stop this class of
  failure next time  -  feed it back into the ledger or the plan.

Then, and only then, retry  -  with the new hypothesis, not the old one.