Agent Self-Debugging
$ARGUMENTS
Structured self-analysis for when the agent is stuck, looping, or producing degraded output.
Step 1: Capture Failure State
Before diagnosing, gather the facts. Answer each question concisely:
| Question |
Answer |
| Last goal/task |
What was the agent trying to accomplish? |
| Actions taken |
List the last 3-5 actions in order |
| Errors or unexpected results |
What went wrong? What was expected vs actual? |
| Attempt count |
How many times has this been tried? |
| Time spent |
Rough estimate of effort so far |
Step 2: Classify the Failure Pattern
Identify which pattern matches the current situation:
| Pattern |
Symptoms |
Common Cause |
| Loop |
Same action repeated 3+ times |
Missing exit condition, wrong approach |
| Drift |
Actions diverge from original goal |
Lost context, scope creep |
| Assumption Error |
Working with wrong mental model |
Didn't read code, assumed behavior |
| Tool Misuse |
Wrong tool for the job |
Grep when should Read, Bash when should Edit |
| Context Overflow |
Forgetting earlier findings |
Too much context, need compaction |
| Wrong Abstraction |
Over-engineering simple task |
Premature abstraction, YAGNI violation |
| Missing Information |
Can't proceed without data |
Need to ask user, read more code |
Pick the single best match. If multiple apply, pick the root cause pattern (the one that, if fixed, would resolve the others).
Step 3: Diagnose Root Cause
Answer these three questions:
- What assumption was wrong? — Identify the specific belief that led to failure.
- What information was missing? — What would have prevented the failure if known earlier?
- What would a fresh start look like? — If starting over with current knowledge, what would the first action be?
Step 4: Select Recovery Action
Choose the smallest recovery action and apply the smallest possible fix — do not restart from scratch unless absolutely necessary:
| Pattern |
Recovery Action |
| Loop |
Stop. Change approach entirely — different tool, different strategy, different angle. |
| Drift |
Re-read the original user request verbatim. Reset scope to exactly what was asked. |
| Assumption Error |
Read the actual code, file, or docs. Do not guess. Verify the mental model. |
| Tool Misuse |
Switch to the correct tool. Read instead of Grep for full context. Edit instead of Bash for file changes. |
| Context Overflow |
Summarize all findings so far in 5 bullet points. Compact and continue. |
| Wrong Abstraction |
Delete the abstraction. Do the simplest, most direct thing that works. |
| Missing Information |
Ask the user exactly ONE specific question. Do not guess. |
Step 5: Produce the Introspection Report
Output exactly this format:
## Introspection Report
**Pattern:** [Loop|Drift|Assumption Error|Tool Misuse|Context Overflow|Wrong Abstraction|Missing Information]
**Root Cause:** [1-2 sentence diagnosis]
**Recovery Action:** [Specific next step]
**Confidence:** [HIGH|MEDIUM|LOW]
### What happened
[Brief timeline of actions taken — 3-5 bullet points max]
### What went wrong
[Specific diagnosis — what assumption failed, what was missed]
### What to do next
[ONE concrete action — not a plan, a single next step]
Rules
- MUST name a specific failure pattern (Loop / Drift / Assumption Error / Tool Misuse / Context Overflow / Wrong Abstraction / Missing Information) — vague self-diagnosis is useless
- MUST ground the diagnosis in concrete evidence (action traces, error messages, tool outputs) — not in feelings or hunches
- NEVER retry the exact same action. If it failed once, it will fail again. Change something.
- NEVER continue a loop "hoping it will work this time". Hope is not a strategy.
- CRITICAL: after 3 failed attempts, escalate to the user with a concrete report of what was tried, what failed, and what you need — do not keep flailing
- MANDATORY: the recovery action is ONE concrete next step, not a multi-phase plan. If you need a plan, use
/plan.
Gotchas
- "Introspection" invoked mid-task can itself become a procrastination loop — spending effort diagnosing instead of acting. If the report takes longer to write than the next concrete action, skip the report and just change approach.
- Context overflow is often invisible from inside the session — the model cannot reliably detect its own forgetting. External signals (user frustration, repeated explanations of the same fact) are the real diagnostic.
- "Wrong abstraction" is frequently misdiagnosed as "Missing information". If adding data does not unlock the next step but simplifying the code does, the abstraction is the problem.
- Ask-the-user is the escape hatch but it has a cost: user context-switching, latency, fatigue. Use it when you truly cannot proceed, not as a habit to avoid commitment.
- The "fresh start" thought experiment works best when written down. Articulating "if starting over, my first action would be X" out loud often reveals the current approach's sunk-cost fallacy.
Self-Correction Checklist
These rules are non-negotiable during recovery:
- Never retry the exact same action. If it failed once, it will fail again. Change something.
- Never continue a loop "hoping it will work this time." Hope is not a strategy.
- Prefer reading code over guessing behavior. Open the file. Read the function. Check the types.
- When in doubt, ask the user rather than making assumptions. One specific question beats three wrong guesses.
- A 2-line fix is better than a 50-line refactor. Solve the immediate problem first.
- Check if the goal is still correct before optimizing the approach. Sometimes the task itself needs clarification.
- If stuck for more than 3 attempts, escalate. Tell the user what you tried, what failed, and what you need.
When NOT to Use
- For debugging user code (not agent self-debugging) — use
/debug
- For analyzing past sessions to find patterns — use
/mem-search or /instinct-review
- For writing a recovery plan that spans multiple steps — use
/plan
- When the user has already described the failure — respond directly, skip the structured introspection
- As a procrastination mechanism — if the next action is obvious, take it instead of writing a report
Quick Self-Check (Use Before Retrying Anything)
Before taking the next action after introspection, answer:
If any answer is "no", stop and address that first.
1---2name: introspect3description: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.4---56# Agent Self-Debugging78$ARGUMENTS910Structured self-analysis for when the agent is stuck, looping, or producing degraded output.1112---1314## Step 1: Capture Failure State1516Before diagnosing, gather the facts. Answer each question concisely:1718| Question | Answer |19|----------|--------|20| **Last goal/task** | What was the agent trying to accomplish? |21| **Actions taken** | List the last 3-5 actions in order |22| **Errors or unexpected results** | What went wrong? What was expected vs actual? |23| **Attempt count** | How many times has this been tried? |24| **Time spent** | Rough estimate of effort so far |2526---2728## Step 2: Classify the Failure Pattern2930Identify which pattern matches the current situation:3132| Pattern | Symptoms | Common Cause |33|---------|----------|--------------|34| **Loop** | Same action repeated 3+ times | Missing exit condition, wrong approach |35| **Drift** | Actions diverge from original goal | Lost context, scope creep |36| **Assumption Error** | Working with wrong mental model | Didn't read code, assumed behavior |37| **Tool Misuse** | Wrong tool for the job | Grep when should Read, Bash when should Edit |38| **Context Overflow** | Forgetting earlier findings | Too much context, need compaction |39| **Wrong Abstraction** | Over-engineering simple task | Premature abstraction, YAGNI violation |40| **Missing Information** | Can't proceed without data | Need to ask user, read more code |4142Pick the **single best match**. If multiple apply, pick the root cause pattern (the one that, if fixed, would resolve the others).4344---4546## Step 3: Diagnose Root Cause4748Answer these three questions:49501. **What assumption was wrong?** — Identify the specific belief that led to failure.512. **What information was missing?** — What would have prevented the failure if known earlier?523. **What would a fresh start look like?** — If starting over with current knowledge, what would the first action be?5354---5556## Step 4: Select Recovery Action5758Choose the **smallest recovery action** and apply the smallest possible fix — do not restart from scratch unless absolutely necessary:5960| Pattern | Recovery Action |61|---------|----------------|62| **Loop** | Stop. Change approach entirely — different tool, different strategy, different angle. |63| **Drift** | Re-read the original user request verbatim. Reset scope to exactly what was asked. |64| **Assumption Error** | Read the actual code, file, or docs. Do not guess. Verify the mental model. |65| **Tool Misuse** | Switch to the correct tool. Read instead of Grep for full context. Edit instead of Bash for file changes. |66| **Context Overflow** | Summarize all findings so far in 5 bullet points. Compact and continue. |67| **Wrong Abstraction** | Delete the abstraction. Do the simplest, most direct thing that works. |68| **Missing Information** | Ask the user exactly ONE specific question. Do not guess. |6970---7172## Step 5: Produce the Introspection Report7374Output exactly this format:7576```markdown77## Introspection Report7879**Pattern:** [Loop|Drift|Assumption Error|Tool Misuse|Context Overflow|Wrong Abstraction|Missing Information]80**Root Cause:** [1-2 sentence diagnosis]81**Recovery Action:** [Specific next step]82**Confidence:** [HIGH|MEDIUM|LOW]8384### What happened85[Brief timeline of actions taken — 3-5 bullet points max]8687### What went wrong88[Specific diagnosis — what assumption failed, what was missed]8990### What to do next91[ONE concrete action — not a plan, a single next step]92```9394---9596## Rules9798- **MUST** name a specific failure pattern (Loop / Drift / Assumption Error / Tool Misuse / Context Overflow / Wrong Abstraction / Missing Information) — vague self-diagnosis is useless99- **MUST** ground the diagnosis in concrete evidence (action traces, error messages, tool outputs) — not in feelings or hunches100- **NEVER** retry the exact same action. If it failed once, it will fail again. Change something.101- **NEVER** continue a loop "hoping it will work this time". Hope is not a strategy.102- **CRITICAL**: after 3 failed attempts, escalate to the user with a concrete report of what was tried, what failed, and what you need — do not keep flailing103- **MANDATORY**: the recovery action is ONE concrete next step, not a multi-phase plan. If you need a plan, use `/plan`.104105## Gotchas106107- "Introspection" invoked mid-task can itself become a procrastination loop — spending effort diagnosing instead of acting. If the report takes longer to write than the next concrete action, skip the report and just change approach.108- Context overflow is often invisible from inside the session — the model cannot reliably detect its own forgetting. External signals (user frustration, repeated explanations of the same fact) are the real diagnostic.109- "Wrong abstraction" is frequently misdiagnosed as "Missing information". If adding data does not unlock the next step but simplifying the code does, the abstraction is the problem.110- Ask-the-user is the escape hatch but it has a cost: user context-switching, latency, fatigue. Use it when you truly cannot proceed, not as a habit to avoid commitment.111- The "fresh start" thought experiment works best when written down. Articulating "if starting over, my first action would be X" out loud often reveals the current approach's sunk-cost fallacy.112113## Self-Correction Checklist114115These rules are non-negotiable during recovery:1161171. **Never retry the exact same action.** If it failed once, it will fail again. Change something.1182. **Never continue a loop "hoping it will work this time."** Hope is not a strategy.1193. **Prefer reading code over guessing behavior.** Open the file. Read the function. Check the types.1204. **When in doubt, ask the user** rather than making assumptions. One specific question beats three wrong guesses.1215. **A 2-line fix is better than a 50-line refactor.** Solve the immediate problem first.1226. **Check if the goal is still correct** before optimizing the approach. Sometimes the task itself needs clarification.1237. **If stuck for more than 3 attempts, escalate.** Tell the user what you tried, what failed, and what you need.124125## When NOT to Use126127- For debugging user code (not agent self-debugging) — use `/debug`128- For analyzing past sessions to find patterns — use `/mem-search` or `/instinct-review`129- For writing a recovery **plan** that spans multiple steps — use `/plan`130- When the user has already described the failure — respond directly, skip the structured introspection131- As a procrastination mechanism — if the next action is obvious, take it instead of writing a report132133---134135## Quick Self-Check (Use Before Retrying Anything)136137Before taking the next action after introspection, answer:138139- [ ] Is this action **different** from what I already tried?140- [ ] Am I working on the **original goal**, not a tangent?141- [ ] Do I have **enough information** to succeed, or am I guessing?142- [ ] Is this the **simplest** approach that could work?143144If any answer is "no", stop and address that first.
softspark