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:

```bash
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:

```text
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:

```text
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

```bash
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