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

Analyze the failure
Formulate a new plan
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/null

Generate 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 structure
view_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.

agent-recovery

Safety Notice

Copy this and send it to your AI assistant to learn