resume

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."

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

1. 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}
{If failed_phase non-null:}
Failed at phase: {failed_phase} — {error}

• Use AskUserQuestion to offer resumption:

Use AskUserQuestion:
  question: "An autonomous run was interrupted at Phase {current_phase}. Continue it?"
  header: "Autonomous Resume"
  options:
    - label: "Continue autonomous run from Phase {current_phase}"
      description: "Run /pbr:autonomous --from {current_phase}"
    - label: "Resume manually (normal resume flow)"
      description: "Continue with the standard resume process"
    - label: "Discard autonomous state"
      description: "Delete .autonomous-state.json and start fresh"
  multiSelect: false

• If user selects Continue autonomous run: display Run: /pbr:autonomous --from {current_phase} and stop (do not proceed with normal resume flow)
• If user selects Resume manually: proceed with normal resume flow (Step 2 onward), keep .autonomous-state.json intact
• If user selects Discard autonomous state: delete .planning/.autonomous-state.json, then proceed with normal resume flow
• If .autonomous-state.json does NOT exist: skip this block entirely, proceed with Step 2

Step 1c: Read Latest Session Snapshot

Check if .planning/sessions/snapshots/ directory exists:

• List files matching *-snapshot.md, sorted alphabetically (newest last).
• If no snapshot files exist, skip this step.
• Read the LAST file (most recent snapshot).
• Parse the frontmatter timestamp field.
• If the timestamp is older than 48 hours from now, skip (snapshot is stale).
• Extract these sections from the snapshot body:
• Working Set -- files that were being edited
• Current Approach -- what the previous session was doing
• Pending Decisions -- unresolved decisions
• Open Questions -- open questions from prior session

Store the extracted snapshot data for use in Step 3a/3b display. Do NOT display anything yet.

Step 2: Search for .continue-here.md Files

Search for .continue-here.md files across all phase directories:

.planning/phases/**/.continue-here.md

If exactly one found:

• This is the resume point. Go to Normal Resume (Step 3a).

If multiple found: **CRITICAL -- DO