sairam0424 Skill — Agent Introspection Debugging
When this skill activates
When an agent is stuck, producing incorrect outputs, hallucinating, wasting tokens on repeated failed attempts, or when reasoning quality has degraded.
Mandatory actions when this skill is active
The 4-Phase Self-Debug Protocol
Phase 1 — Failure Capture Document exactly what went wrong:
- What was the agent trying to accomplish?
- What did it actually produce?
- What was the expected outcome?
- What context was available at the time?
- How many tokens/iterations were spent before failure was detected?
Phase 2 — Diagnosis Identify WHY the reasoning failed:
| Failure Mode | Symptoms | Root Cause |
|---|---|---|
| Context overflow | Repeating earlier mistakes, forgetting constraints | Context window exceeded, compaction lost key info |
| Hallucination | Confident claims about non-existent code/APIs | Insufficient grounding, no verification step |
| Loop spinning | Same action repeated 3+ times without progress | No exit condition, stuck-detection not triggered |
| Scope creep | Task expanding beyond original spec | Missing constraints, no scope boundary check |
| Stale context | Acting on outdated information | Context not refreshed, old file contents cached |
| Wrong persona | Security review giving UX advice | Persona mismatch, wrong skill loaded |
Phase 3 — Contained Recovery Fix the problem WITHOUT expanding the blast radius:
- Identify the MINIMUM change needed to recover
- Do NOT restart from scratch unless absolutely necessary
- Do NOT make speculative changes beyond the fix
- Verify the recovery actually works (don't assume)
- If recovery fails after 2 attempts: ESCALATE (do not keep trying)
Phase 4 — Introspection Report
Write structured output to .planning/INTROSPECTION-[timestamp].md:
# Introspection Report
Date: [timestamp]
Session: [session-id]
Failure type: [from diagnosis table]
## What Happened
[1-2 sentences describing the failure]
## Root Cause
[Why this happened — be specific]
## Recovery Action
[What was done to fix it]
## Prevention
[What should change to prevent recurrence]
- [ ] Instinct to capture? [yes/no — if yes, create via learn-instinct]
- [ ] Skill gap? [yes/no — if yes, what skill is missing]
- [ ] Config change needed? [yes/no — what setting]
Introspection Triggers
Automatically invoke this skill when:
- Stuck-detector fires (3 iterations, no progress)
- Token usage exceeds 3x estimate for a task
- Same error appears 2+ times in consecutive attempts
- User says "stop", "that's wrong", "you're stuck", "try again differently"
During introspection
- PAUSE all other work — introspection is the priority
- Read recent AUDIT entries for context on what was attempted
- Check SHARED_TASK_NOTES.md for cross-iteration patterns
- Never blame external factors without evidence (check your own reasoning first)
After introspection
- Log introspection event in AUDIT
- Consider whether this warrants a new instinct (via continuous-learning)
- Resume work only after recovery is verified
- If pattern repeats: escalate to user, do not keep self-debugging