Agent Recovery Skill
Protocols for when the agent is stuck, context is degraded, or session needs migration.
When to Use
- Agent is making repeated mistakes
- Long conversation causing hallucinations
- Need to hand off to fresh agent
- Context window is full
Option 1: Escalate (Handoff Report)
Use when: Agent is stuck and can't solve the problem.
Steps
- Undo broken changes:
git status
git checkout -- .- Generate
docs/escalation_report.md:
# Escalation Handoff Report
**Generated:** [Date/Time]
**Original Issue:** [GitHub Issue # or description]
## PART 1: THE DAMAGE REPORT
### 1.1 Original Goal
[The task you were asked to complete]
### 1.2 Observed Failure
[EXACT error message]
### 1.3 Failed Approach
[Strategy you attempted]
### 1.4 Key Files Involved
- `path/to/file1.ts`
### 1.5 Best-Guess Diagnosis
[Why approach failed]
## PART 2: FULL FILE CONTENTS
[EMBED entire content of each file]
## PART 3: DIRECTIVE FOR ORCHESTRATOR
1. Analyze the failure
2. Formulate a new plan
3. Execute or hand off- Open new session and paste the report content.
Option 2: Migrate (Context Snapshot)
Use when: Chat is stale, need fresh session with same context.
Auto-Detect Context
cat docs/Project_Requirements.md 2>/dev/null
git log --oneline -20
gh issue list --state open --limit 10 --json number,title
cat docs/Coding_Guidelines.md 2>/dev/nullGenerate docs/migration_snapshot.md:
# State Snapshot Handoff Prompt
## To the New AI: Adopt This Identity
You are the **VibeCode Project Orchestrator**...
## Project Details
- **Name:** [from PRD]
- **Stack:** [from PRD]
## Milestones
[From git log]
## Current Status
- In Progress: [from GitHub]
- Next: [from roadmap]
## Key Files
- `docs/Project_Requirements.md`
- `docs/Coding_Guidelines.md`
## First Action
Read files above, then ask: "What would you like to work on next?"Option 3: Reset (Mid-Conversation)
Use when: Agent is making mistakes but can recover.
🛑 HARD STOP CHECKLIST
□ Did I READ the target file with view_file BEFORE editing?
□ Did I copy the EXACT target content, including whitespace?
□ Am I editing LESS than 50 lines at a time?
□ Did I verify all variable names exist in scope?
□ Did I check props are destructured in function signature?Common Mistakes
| Pattern | Fix |
|---|---|
| Duplicate lines | Read file first, count declarations |
| Missing destructuring | Check props signature |
| Broken JSX | Close tags in same edit |
| Phantom variables | grep in file before using |
| Edit offset drift | Re-read file after each edit |
File Edit Protocol
view_file_outline→ Understand structureview_file(exact range) → Copy PRECISE content- Make edit with MINIMAL scope
- Re-check file before next edit
Verified Completion
Before saying "done":
npx tsc --noEmit # MUST pass- No duplicate declarations?
- No missing imports?
- Task actually solved?
If errors persist after 3 fix attempts → use Escalate.