Agent Introspection Debugging

When to Activate

• Maximum tool call / loop-limit failures
• Repeated retries with no forward progress
• Context growth or prompt drift that starts degrading output quality
• File-system or environment state mismatch between expectation and reality
• Tool failures that are likely recoverable with diagnosis and a smaller corrective action

Scope Boundaries

• capturing failure state before retrying blindly
• diagnosing common agent-specific failure patterns
• applying contained recovery actions
• producing a structured human-readable debug report

• feature verification after code changes; use

  verification-loop

• framework-specific debugging when a narrower ECC skill already exists
• runtime promises the current harness cannot enforce automatically

Four-Phase Loop

Phase 1: Failure Capture

• error type, message, and stack trace when available
• last meaningful tool call sequence
• what the agent was trying to do
• current context pressure: repeated prompts, oversized pasted logs, duplicated plans, or runaway notes
• current environment assumptions: cwd, branch, relevant service state, expected files

## Failure Capture
- Session / task:
- Goal in progress:
- Error:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Environment assumptions to verify:

Phase 2: Root-Cause Diagnosis

ECONNREFUSED

429

• is this a logic failure, state failure, environment failure, or policy failure?
• did the agent lose the real objective and start optimizing the wrong subtask?
• is the failure deterministic or transient?
• what is the smallest reversible action that would validate the diagnosis?

Phase 3: Contained Recovery

• stop repeated retries and restate the hypothesis
• trim low-signal context and keep only the active goal, blockers, and evidence
• re-check the actual filesystem / branch / process state
• narrow the task to one failing command, one file, or one test
• switch from speculative reasoning to direct observation
• escalate to a human when the failure is high-risk or externally blocked

## Recovery Action
- Diagnosis chosen:
- Smallest action taken:
- Why this is safe:
- What evidence would prove the fix worked:

Phase 4: Introspection Report

## Agent Self-Debug Report
- Session / task:
- Failure:
- Root cause:
- Recovery action:
- Result: success | partial | blocked
- Token / time burn risk:
- Follow-up needed:
- Preventive change to encode later:

Recovery Heuristics

1. Restate the real objective in one sentence.
2. Verify the world state instead of trusting memory.
3. Shrink the failing scope.
4. Run one discriminating check.
5. Only then retry.

• retrying the same action three times with slightly different wording

• capture failure
• classify the pattern
• run one direct check
• change the plan only if the check supports it

Integration with ECC

• Use

  verification-loop

  after recovery if code was changed.
• Use

  continuous-learning-v2

  when the failure pattern is worth turning into an instinct or later skill.
• Use

  council

  when the issue is not technical failure but decision ambiguity.
• Use

  workspace-surface-audit

  if the failure came from conflicting local state or repo drift.

Output Standard

• the failure pattern
• the root-cause hypothesis
• the recovery action
• the evidence that the situation is now better or still blocked