/resume

name: resume
description: "Pick up where you left off. Restores context and suggests next action."
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
argument-hint: "[--from <file>]"

**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► RESUMING SESSION                           ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:resume-work — Resume Previous Session

You are running the **resume** skill. Your job is to find the last pause point, restore context for the user, and suggest the next action so they can continue seamlessly.

This skill runs **inline** (no Task delegation).

---

Core Principle

**Get the user back to work in under 30 seconds.** Read the handoff, show what matters, and suggest the next command. Don't make them re-discover their own project state.

---

Resumption Priority Hierarchy

When resuming, scan for conditions in this priority order. Handle the HIGHEST priority item first:

1. 🔴 UAT-BLOCKER (diagnosed) → Fix must come first
2. 🟡 Interrupted agent → Resume agent from checkpoint
3. 🟡 .continue-here checkpoint → Resume from checkpoint
4. 🟡 Incomplete plan → Complete plan execution
5. 🟢 Phase complete → Transition to next phase
6. 🟢 Ready to plan/execute → Normal workflow

Scanning for Priority Items

Before presenting the standard resume view, check:

1. **UAT Blockers**: Search for VERIFICATION.md files with `status: gaps_found` in any phase. If found and gaps are marked as blocking, surface them first: "Phase {N} has {count} blocking verification gaps. These should be fixed before continuing."

2. **Interrupted Agents**: Check for `.checkpoint-manifest.json` files in phase directories with `checkpoints_pending` entries. These indicate a build was interrupted mid-checkpoint.

3. **Stale .continue-here.md**: If the file references commits that don't exist in git log, warn about state corruption.

Auto-Reconcile STATE.md Against Filesystem

On every resume, reconcile STATE.md claims against filesystem reality:

pbr-tools state check-progress

Parse the JSON output:

• If `discrepancies` array is empty: proceed silently (state is consistent)
• If discrepancies found with `severity: "corruption"`: present repair and ask for confirmation via AskUserQuestion
• If discrepancies found with `severity: "drift"`: auto-repair silently and note the changes
• Log all repairs to `.planning/logs/events.jsonl` with category `state-reconcile`

If the CLI fails, display a branded ERROR box: "Failed to check state consistency." and proceed with resume (non-blocking — state reconciliation is advisory).

---

Flow

Step 1: Read STATE.md

Read `.planning/STATE.md` for the last known position.

**Extract from frontmatter:**

• Current phase and plan
• `session_last` — when the last session ended (ISO timestamp)
• `session_stopped_at` — brief description of where work stopped
• `session_resume` — path to .continue-here.md file

**If `session_last` exists in frontmatter**, display it immediately before any other output:

Last session: {session_last}
Stopped at: {session_stopped_at}

This gives the user instant context before the full resume analysis runs.

**Also extract from body:**

• Session Continuity section (if exists):
• Last paused date
• Continue file location
• Suggested next action

**CRITICAL -- DO NOT SKIP: After successful resume**, clear `session_stopped_at` from STATE.md frontmatter (set to empty string or remove) to indicate the session has been resumed. Keep `session_last` and `session_resume` intact for reference.

**If STATE.md doesn't exist:**

• Go to **Recovery Flow** (Step 4)

Step 1b: Check for HANDOFF.json and WAITING.json

**Before searching for .continue-here.md**, check for structured state files:

HANDOFF.json (Machine-Readable Pause State)

Check if `.planning/HANDOFF.json` exists:

• If found, parse it and extract structured resume context:
• Display: phase, plan, current task, next action, blockers, human actions pending
• Use this data to populate the resume display (it's more reliable than .continue-here.md)
• After successful resume, **delete HANDOFF.json** (one-shot consumption)
• Continue to Step 3a (Normal Resume) using the HANDOFF.json data alongside .continue-here.md
• If not found, proceed normally to Step 2

WAITING.json (External Wait State)

Check if `.planning/WAITING.json` exists:

• If found, parse it and display the waiting state:

  Project is in WAITING state
  Reason: {reason}
  Waiting since: {created_at}
  Expected duration: {expected_duration}

• Offer to resume: "The project was waiting on an external action. If the action is complete, run `/pbr:resume-work` to clear the waiting state and continue."
• If the user confirms the wait is resolved, delete WAITING.json and proceed with normal resume
• If not found, proceed normally to Step 2

Autonomous State (.autonomous-state.json)

Check if `.planning/.autonomous-state.json` exists:

• If found, parse it and extract:
• `current_phase` -- the phase the autonomous run was on when interrupted
• `completed_phases` -- list of phases already completed
• `branch_state` -- map of phase -> branch name (may be empty `{}`)
• `started_at` -- when the run began
• `failed_phase` / `error` -- whether the run failed vs. was interrupted
• Display a summary block:

Autonomous Run Detected
Started: {started_at}
Completed phases: {completed_phases list, or "none"}
Current phase: {current_phase}
{If branch_state non-empty:}
Active branch: {branch for current_phase, if present}