agent-debug-loop

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: