/recover — Context Recovery After Compaction

Purpose: Help you get back up to speed after Claude Code context compaction. Automatically detects in-progress work (RPI runs, evolve cycles), loads relevant knowledge, and summarizes what you were doing and what's next.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

CLI dependencies: gt, ao, bd — all optional. Shows what's available, skips what isn't.

Quick Start

bash

/recover              # Full recovery dashboard
/recover --json       # Machine-readable JSON output

Execution Steps

Step 1: Detect In-Progress Sessions (Parallel)

Run ALL of the following in parallel bash calls:

Call 1 — RPI Phased State:

bash

if [ -f .agents/rpi/phased-state.json ]; then
  echo "=== RPI_STATE ==="
  cat .agents/rpi/phased-state.json
else
  echo "RPI_STATE=NONE"
fi

Call 2 — Evolve Cycle History:

bash

if [ -f .agents/evolve/cycle-history.jsonl ]; then
  echo "=== EVOLVE_STATE ==="
  tail -3 .agents/evolve/cycle-history.jsonl
else
  echo "EVOLVE_STATE=NONE"
fi

Call 3 — Git Recent Changes:

bash

echo "=== GIT_STATUS ==="
git status --short

echo "=== GIT_LOG ==="
git log --oneline -5

echo "=== GIT_BRANCH ==="
git branch --show-current

Call 4 — Work Queue State:

bash

if command -v bd &>/dev/null; then
  echo "=== IN_PROGRESS ==="
  bd list --status in_progress 2>/dev/null | head -3
  echo "=== READY ==="
  bd ready 2>/dev/null | head -3
else
  echo "BD_UNAVAILABLE"
fi

Call 5 — Knowledge and Messages:

bash

# Knowledge artifacts
echo "=== KNOWLEDGE_COUNT ==="
echo "Learnings=$(ls .agents/learnings/ 2>/dev/null | wc -l | tr -d ' ')"
echo "Patterns=$(ls .agents/patterns/ 2>/dev/null | wc -l | tr -d ' ')"

# Inbox if gt available
if command -v gt &>/dev/null; then
  echo "=== MESSAGES ==="
  gt mail inbox 2>/dev/null | head -3
else
  echo "GT_UNAVAILABLE"
fi

Step 2: Load Context from Knowledge Base

If RPI state detected, run:

bash

if command -v ao &>/dev/null; then
  ao inject --apply-decay --format markdown --max-tokens 2000
fi

Step 3: Parse and Summarize Session State

Extract from collected data:

RPI Detection: If
```
.agents/rpi/phased-state.json
```
exists:
- Extract
```
goal
```
  ,
```
epic_id
```
  ,
```
phase
```
  ,
```
cycle
```
  ,
```
started_at
```
- Map phase number to phase name (1=research, 2=plan, 3=implement, 4=validate)
- Show elapsed time since started_at
Evolve Detection: If
```
.agents/evolve/cycle-history.jsonl
```
exists:
- Read last entry for most recent cycle
- Extract
```
goals_fixed
```
  ,
```
result
```
  ,
```
timestamp
```
- Show latest cycle summary
Recent Work: From git log:
- Last 3 commits (extracted in Call 3)
- Uncommitted changes count
Pending Work: From beads:
- In-progress issues (up to 3)
- Ready issues count
Knowledge State:
- Total learnings and patterns available
- Unread messages count if gt available

Step 4: Render Recovery Dashboard

Assemble gathered data into this format:

══════════════════════════════════════════════════════════════
  Context Recovery Dashboard
══════════════════════════════════════════════════════════════

IN-PROGRESS RPI RUN
  Epic: <epic_id>
  Goal: <first 80 chars of goal>
  Phase: <phase name: research | plan | implement | validate>
  Cycle: <cycle #>
  Started: <time ago (e.g., "2 hours ago")>
  Status: <PHASE_START | IN_PROGRESS | READY_FOR_GATE | ...>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

RECENT EVOLVE CYCLE (IF NO RPI)
  Cycle: <cycle #>
  Latest Goal: <goal_id or summary>
  Result: <result>
  Items Completed: <count or "—">
  Timestamp: <time ago>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

[NO ACTIVE SESSION]
  No RPI run or evolve cycle in progress.
  Last activity: <time of last commit or "unknown">

IN-PROGRESS WORK
  <list up to 3 in-progress issues with IDs>
  <or "No in-progress work">

READY TO WORK
  <count of ready issues>
  <or "No ready issues">

RECENT COMMITS
  <last 3 commits>

PENDING CHANGES
  <uncommitted file count or "clean">

KNOWLEDGE AVAILABLE
  Learnings: <count>  Patterns: <count>

INBOX
  <message count or "No messages" or "gt not installed">

──────────────────────────────────────────────────────────────
SUGGESTED NEXT ACTION
  <state-aware command from Step 5>
──────────────────────────────────────────────────────────────

QUICK COMMANDS
  /status       Current workflow dashboard
  /research     Deep codebase exploration
  /plan         Decompose work into issues
  /implement    Execute a single issue
  /crank        Autonomous epic execution
  /vibe         Validate code quality
══════════════════════════════════════════════════════════════

Step 5: Suggest Next Action (State-Aware)

Evaluate context top-to-bottom. Use the FIRST matching condition:


/inbox
/research
/pre-mortem
/implement <next-issue-id>
/post-mortem
/evolve --resume
/implement <issue-id>
/implement <first-ready-id>
/vibe recent
/status

Priority	Condition	Suggestion
1	Unread messages in inbox	"Check messages: `/inbox` "
2	RPI run in-progress + phase=research	"Continue research: `/research` or `/plan` if ready"
3	RPI run in-progress + phase=plan	"Review plan: `/pre-mortem` to validate before coding"
4	RPI run in-progress + phase=implement	"Resume implementation: `/implement <next-issue-id>` "
5	RPI run in-progress + phase=validate	"Complete cycle: `/post-mortem` to extract learnings"
6	Evolve cycle in-progress	"Continue autonomous improvements: `/evolve --resume` "
7	In-progress issues exist	"Continue work: `/implement <issue-id>` "
8	Ready issues available	"Pick next issue: `/implement <first-ready-id>` "
9	Uncommitted changes	"Review changes: `/vibe recent` "
10	Clean state, nothing pending	"Session recovered. Start with `/status` to plan next work"

Step 6: JSON Output (--json flag)

If the user passed

--json

, output all recovery data as structured JSON:

json

{
  "session_type": "rpi|evolve|none",
  "rpi": {
    "epic_id": "ag-l2pu",
    "goal": "Implement...",
    "phase": 2,
    "phase_name": "plan",
    "cycle": 1,
    "started_at": "2026-02-15T14:33:36-05:00",
    "elapsed_minutes": 120
  },
  "evolve": {
    "cycle": 3,
    "result": "improved",
    "goals_fixed": ["goal1", "goal2"],
    "timestamp": "2026-02-15T22:00:00-05:00"
  },
  "work_state": {
    "in_progress_count": 3,
    "in_progress_issues": ["ag-042.1", "ag-042.2"],
    "ready_count": 5,
    "uncommitted_changes": 2
  },
  "git": {
    "branch": "main",
    "recent_commits": [
      "7de51c8 feat: wave 2 — structural assertions",
      "25004f8 fix: replace per-wave vibe gate"
    ]
  },
  "knowledge": {
    "learnings_count": 12,
    "patterns_count": 5
  },
  "inbox": {
    "unread_count": 0
  },
  "suggestion": {
    "priority": 4,
    "message": "Resume implementation: /implement ag-042.1"
  }
}

Render this with a single code block. No visual dashboard when

--json

is active.

Examples

Recovery After Compaction Mid-RPI

User says:

/recover

What happens:

Agent runs 5 parallel bash calls to gather state
Agent detects RPI run in phased-state.json (phase=2, epic ag-l2pu)
Agent runs
```
ao inject
```
to load relevant knowledge
Agent shows goal, current phase (plan), cycle 1, started 2 hours ago
Agent lists 2 in-progress issues and 3 ready issues
Agent shows clean git state, recent commit
Agent suggests: "Review plan:
```
/pre-mortem
```
to validate before coding"

Result: Dashboard confirms in-progress RPI session, loads context, suggests next step.

Recovery After Compaction With Evolve Cycle

User says:

/recover

What happens:

Agent gathers state in parallel
Agent finds no RPI run
Agent detects evolve cycle (most recent: cycle 3, result "improved", goals_fixed=["goal1", "goal2"])
Agent shows timestamp (1 hour ago), items_completed (8)
Agent loads knowledge with
```
ao inject
```
Agent suggests: "Continue autonomous improvements:
```
/evolve --resume
```
"

Result: Dashboard confirms evolve cycle, shows progress, offers resume command.

Recovery in Clean State (No Active Session)

User says:

/recover

What happens:

Agent gathers state in parallel
Agent finds no RPI run, no evolve cycle
Agent shows last 3 commits only
Agent finds no in-progress work, no ready issues
Agent shows 12 learnings available from knowledge base
Agent suggests: "Session recovered. Start with
```
/status
```
to plan next work"

Result: Dashboard confirms clean state, points user to entry points.

Troubleshooting

Problem	Cause	Solution
Shows "BD_UNAVAILABLE" or "GT_UNAVAILABLE"	CLI tools not installed or not in PATH	Install missing tools: `brew install bd` or `brew install gt` . Skill gracefully degrades by showing available state only.
RPI state shows wrong phase	Stale phased-state.json not updated	Check timestamp of `.agents/rpi/phased-state.json` . If stale, it may be from a previous run. Run `/status` to verify current phase.
Evolve history shows wrong cycle	Old cycle-history.jsonl entries not pruned	Tail -3 shows most recent entries. Check all entries with `tail -20 .agents/evolve/cycle-history.jsonl` .
Knowledge injection fails silently	ao CLI not installed or no knowledge artifacts	Ensure ao installed: `brew install ao` . If no learnings exist, run `/post-mortem` to seed the knowledge base.
Suggested action doesn't match context	State-aware rules didn't capture edge case	Use `--json` to inspect raw state and verify which condition matched. Review priority table in Step 5.
JSON output malformed	Parallel bash calls returned unexpected format	Check each bash call individually. Ensure jq parsing works on actual data. Validate JSON structure before returning to user.

recover

NPX Install

Tags

SKILL.md Content

/recover — Context Recovery After Compaction

Quick Start

Execution Steps

Step 1: Detect In-Progress Sessions (Parallel)

Step 2: Load Context from Knowledge Base

Step 3: Parse and Summarize Session State

Step 4: Render Recovery Dashboard

Step 5: Suggest Next Action (State-Aware)

Step 6: JSON Output (--json flag)

Examples

Recovery After Compaction Mid-RPI

Recovery After Compaction With Evolve Cycle

Recovery in Clean State (No Active Session)

Troubleshooting