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}
{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 NOT SKIP: Present the following choice to the user via AskUserQuestion before proceeding: Use the pause-point-select pattern (see skills/shared/gate-prompts.md):

Use AskUserQuestion: question: "Found multiple pause points. Which would you like to resume?" header: "Resume" options: - label: "Phase {A}" description: "Paused {date}, {brief context}" - label: "Phase {B}" description: "Paused {date}, {brief context}" - label: "Phase {C}" description: "Paused {date}, {brief context}" - label: "Phase {D}" description: "Paused {date}, {brief context}" multiSelect: false

Build options dynamically from discovered .continue-here.md files. Include phase name and pause date in each option. If more than 4 pause points exist, show the 4 most recent and replace the last option with:

• label: "Show earlier" description: "See older pause points"

When "Show earlier" is selected, re-prompt with the next batch of 4.

Use the selected pause point for the rest of the resume flow.

If none found:

• Check STATE.md for position info
• If STATE.md has position: go to Inferred Resume (Step 3b)
• If STATE.md has no position: go to Recovery Flow (Step 4)

Step 3a: Normal Resume (from .continue-here.md)

1. Read the .continue-here.md file completely

2. Parse sections. If the file contains <current_state>, parse XML sections. Otherwise, fall back to parsing markdown headers (## Position, ## Completed This Session, etc.) for backward compatibility with old-format files.

   • <current_state> -- phase, plan, status, branch, working files
   • <completed_work> -- what was done last session
   • <remaining_work> -- what's left in this phase
   • <decisions_made> -- key decisions that affect future work
   • <context> -- approach, reasoning, things to watch out for
   • <next_action> -- the single most important next step with exact command

3. Display the resume context using the branded banner:

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

Resuming session from {pause date}

Position: Phase {N} -- {name}
Plan: {M} of {total}
Status: {status}

Completed last session:
{bulleted list of completed work}

{If snapshot loaded and not stale:}
Last session context:
- Working on: {files from Working Set, max 5}
- Approach: {Current Approach text, truncated to 150 chars}
{If pending decisions exist:}
- Pending decisions: {count} unresolved
{If open questions exist:}
- Open questions: {count} remaining

Remaining in this phase:
{bulleted list of remaining plans}

{If decisions were made:}
Key decisions:
{bulleted list of decisions}

{If context section has content:}
Session context:
{approach and reasoning from <context> section}

{If blockers exist:}
Blockers:
{bulleted list of blockers}

4. Validate the resume point:

   • Check that the phase directory still exists
   • Check that the plan files mentioned still exist
   • Check git log to verify commits mentioned in completed work
   • If anything is inconsistent, warn: "Some state has changed since the pause. {details}"

5. Present the next action from the continue-here file. When a <next_action> section exists with a Command: field, prefer that over inferring the next action from state -- the pause skill captured the exact command to run.

If only one clear next action exists, present it with branded routing:

╔══════════════════════════════════════════════════════════════╗
║  ▶ NEXT UP                                                   ║
╚══════════════════════════════════════════════════════════════╝

**{explanation from continue-here}**

`{suggested command}`

<sub>`/clear` first → fresh context window</sub>

If multiple reasonable actions exist (e.g., the continue-here suggests one thing but the filesystem state suggests another): CRITICAL -- DO NOT SKIP: Present the following choice to the user via AskUserQuestion before proceeding: Use the action-routing pattern (see skills/shared/gate-prompts.md):

Use AskUserQuestion: question: "How would you like to proceed?" header: "Next Step" options: - label: "{continue-here suggestion}" description: "Resume from pause point" - label: "{filesystem-inferred action}" description: "Based on current state" - label: "Show status" description: "Run /pbr:progress for full overview" - label: "Something else" description: "Enter a different command" multiSelect: false

After user selects an option:

• Display "Run: /pbr:{action} {args}" so the user can execute it
• This skill does not auto-execute — it suggests and the user acts

6. Clean up:
   • DO NOT delete the .continue-here.md file yet
   • It will be naturally superseded when the next pause happens
   • Or it can be manually removed after the user confirms they're back on track

Step 3b: Inferred Resume (from STATE.md only)

When there's no .continue-here.md but STATE.md has position info:

1. Read STATE.md position
2. Scan the current phase directory for plan and summary files
3. Determine what's complete vs. remaining
4. Present a reduced resume context:

Resuming from STATE.md (no pause file found)

Position: Phase {N} -- {name}
Progress: {completed}/{total} plans complete

{If snapshot loaded and not stale:}
Last session context:
- Working on: {files from Working Set, max 5}
- Approach: {Current Approach text, truncated to 150 chars}
{If pending decisions exist:}
- Pending decisions: {count} unresolved
{If open questions exist:}
- Open questions: {count} remaining

{Plans with summaries listed as complete}
{Plans without summaries listed as remaining}

Note: No detailed pause context available. Run `/pbr:progress` for a full overview.

5. Suggest the next action based on phase state using the action-routing pattern:

CRITICAL -- DO NOT SKIP: Present the following choice to the user via AskUserQuestion before proceeding: Use AskUserQuestion: question: "What would you like to do next?" header: "Next Step" options: (build dynamically from phase state) - label: "/pbr:execute-phase {N}" description: "Continue building (plans remaining)" - label: "/pbr:verify-work {N}" description: "Review completed phase" - label: "/pbr:plan-phase {N} --gaps" description: "Fix verification gaps" - label: "/pbr:plan-phase {N+1}" description: "Plan the next phase" multiSelect: false

Show only the options that apply to the current state (1-3 real options + "Something else").

Step 4: Recovery Flow

When neither .continue-here.md nor STATE.md position data exists:

1. Check if .planning/ directory exists at all

   • If no, display:

     ╔══════════════════════════════════════════════════════════════╗
     ║  ERROR                                                       ║
     ╚══════════════════════════════════════════════════════════════╝
     
     No Plan-Build-Run project found.
     
     **To fix:** Run `/pbr:new-project` to start a new project, or `/pbr:map-codebase` to analyze an existing codebase.
     

   • Stop here.

2. If .planning/ exists, scan for any project state:

   • Check for ROADMAP.md
   • Check for any phase directories
   • Check for any SUMMARY.md files
   • Check for config.json

3. If some state exists:

Found a Plan-Build-Run project but no pause point.

Project has:
- {count} phases in ROADMAP.md
- {count} phase directories
- {count} completed plans (SUMMARY.md files)

Attempting to determine position...

4. Infer position:

   • Find the last phase with SUMMARY.md files
   • Check if all plans in that phase have summaries
   • Determine the next action

5. Present recovery status:

Best guess for current position:

Phase {N}: {name}
- {X} of {Y} plans completed
- Last activity: {date from most recent SUMMARY.md or git log}

Suggested: Run `/pbr:progress` for a full overview, then choose your next action.

---

Resume Routing

After displaying context, route to the appropriate action:

Situation	Suggested Action
Autonomous run interrupted	/pbr:autonomous --from {N}
Mid-phase, plans remaining	/pbr:execute-phase {N} (executor will skip completed plans)
Phase complete, not reviewed	/pbr:verify-work {N}
Phase reviewed, has gaps	/pbr:plan-phase {N} --gaps
Phase complete and verified	/pbr:plan-phase {N+1}
Between milestones	/pbr:new-milestone
Active debug session	/pbr:debug (will offer to resume)
Pending todos exist	Mention: "Also {count} pending todos. /pbr:check-todos"

---

State Validation

When resuming, validate that the project state is consistent:

Git State Check

git status --short

If there are uncommitted changes:

• Warn: "There are uncommitted changes in the working directory."
• List the changed files
• Suggest: "These may be from an interrupted build. Review them before continuing."

Plan-Summary Consistency

For each plan file in the current phase:

• Check if SUMMARY.md exists
• If SUMMARY.md exists, check its status field
• If status is partial or failed, warn

Continuation Context Freshness

If .continue-here.md is more than 7 days old:

• Warn: "This pause point is {N} days old. The codebase may have changed."
• Suggest: "Run /pbr:progress to verify the current state before continuing."

---

Reference: skills/shared/error-reporting.md for branded error output patterns.

Edge Cases

.continue-here.md references deleted files

• Warn about each missing file
• Attempt to find equivalent files (renamed, moved)
• If phase directory is gone: "Phase {N} directory was removed. This pause point is invalid."
• Suggest /pbr:progress for recovery

Git history doesn't match .continue-here.md

• Commits referenced in the handoff may have been rebased, amended, or rolled back
• Warn: "Some commits referenced in the pause file couldn't be found in git history."
• Don't treat this as fatal — the file system state matters more than commit hashes

User made changes between sessions (outside Plan-Build-Run)

• The user may have manually edited files, committed changes, or modified configs
• These changes won't be reflected in .continue-here.md
• Check git log for commits not referenced in the handoff
• If found: "Found {N} commits since the last pause that aren't tracked in the handoff."

Multiple users / branches

• If git branch has changed since the pause:
  • Warn: "You're on branch {current} but the pause was on {paused-branch}."
  • Suggest switching branches or starting fresh

Empty project (just initialized)

• If .planning/ exists but only has config.json, display:

  ╔══════════════════════════════════════════════════════════════╗
  ║  ERROR                                                       ║
  ╚══════════════════════════════════════════════════════════════╝
  
  Project was initialized but no work has been done.
  
  **To fix:** Run `/pbr:plan-phase 1` to start planning, or `/pbr:discuss-phase 1` to talk through the first phase.
  

---

Anti-Patterns

1. DO NOT auto-execute the suggested next action — just suggest it
2. DO NOT delete .continue-here.md during resume — let the next pause overwrite it
3. DO NOT modify any project files — resume is read-only (except cleaning up stale state)
4. DO NOT assume .continue-here.md is accurate — always validate against the file system
5. DO NOT show overwhelming amounts of detail — focus on actionable information
6. DO NOT ignore inconsistencies — surface them as warnings
7. DO NOT skip the git state check — uncommitted changes are important to surface
8. DO NOT suggest multiple actions without clear priority — one primary suggestion