resume-work

# /resume-work - Session State Restoration

## Overview

This skill reconstructs session state from handoff artifacts so work can continue without wasting time re-reading files and re-discovering decisions. It is the consumer half of the pause/resume pair — `/pause-work` creates the artifacts, `/resume-work` consumes them.

The priority cascade exists because handoff quality varies:
1. **HANDOFF.json** — Best case. Machine-readable, structured, created by explicit `/pause`. Contains reasoning context.
2. **.continue-here.md** — Good case. Human-readable prose. May exist without JSON if user wrote it manually.
3. **task_plan.md** — Fallback. Records task structure but not session reasoning. Better than nothing.
4. **git log + git status** — Last resort. Can infer recent activity but cannot reconstruct reasoning or rejected approaches.

Each level down the cascade loses more context, so the skill always starts from the top.

---

## Instructions

### Phase 1: DISCOVER

**Goal**: Find the best available state source using the priority cascade. Always check sources in order to ensure no high-quality context is lost (higher sources contain richer information than lower ones).

**Step 1: Identify project root**

```bash
git rev-parse --show-toplevel
```

**Step 2: Check for HANDOFF.json (Priority 1)**

Look for `{project_root}/HANDOFF.json`. If found:
- Read and parse the JSON
- Check `created_at` timestamp — if older than 24 hours, set `stale_warning = true` and plan to alert user before proceeding
- This is the richest source: proceed to Phase 2 with full structured data
- Also read `.continue-here.md` if it exists (for supplementary prose context)

**Step 3: Check for .continue-here.md (Priority 2)**

If no HANDOFF.json but `.continue-here.md` exists:
- Read the prose content
- Extract what you can: task description, completed items, next action, decisions
- Note that reasoning context may be limited compared to JSON handoff

**Step 4: Check for task_plan.md (Priority 3)**

If neither handoff file exists but `task_plan.md` exists:
- Read the plan
- Extract: completed phases `[x]`, remaining phases `[ ]`, decisions, errors, current status
- Note: this source captures task structure but not session reasoning

**Step 5: Fall back to git reconstruction (Priority 4)**

If no handoff files and no task_plan.md:

```bash
# Recent activity
git log --oneline -20

# Current branch context
git branch --show-current

# Uncommitted work
git status --short

# What's changed
git diff --stat
```

Synthesize a best-effort summary from git state. This is the least precise reconstruction — it shows WHAT happened but not WHY. Never skip to this source if higher-priority sources exist, as that would lose context.

**Step 6: Set reconstruction quality indicator**

| Source | Quality | Missing |
|--------|---------|---------|
| HANDOFF.json | Full | Nothing — richest source |
| .continue-here.md | Good | Structured data, may lack reasoning detail |
| task_plan.md | Partial | Session reasoning, rejected approaches, mental model |
| git log | Minimal | All reasoning context, decisions rationale, next action specifics |

**GATE**: At least one state source found and read. If ALL sources are empty (no handoff, no plan, no git history), inform user: "No session state found. Use /do to start a new task."

### Phase 2: RECONSTRUCT

**Goal**: Build a coherent state picture from available sources. Always present a status dashboard before taking action — the user needs to confirm the reconstructed state matches reality, since self-assessment of "what I was doing" is inherently fallible.

**Step 1: Verify uncommitted files**

If the handoff reports `uncommitted_files`, check whether they still exist (work may have been lost during worktree cleanup or manual revert):

```bash
# For each file in uncommitted_files list
git status --short -- <file>
```

Flag any files that were listed as uncommitted but are now missing — these represent potential work loss.

**Step 2: Check for false completions**

If the handoff reports `false_completions`, verify those placeholder markers still exist in the codebase. They may have been fixed by manual intervention between sessions.

**Step 3: Synthesize status dashboard**

Build the dashboard from available data. This dashboard is your knowledge checkpoint — it prevents false assumptions from carrying into the resumed session:

```
===================================================================
 SESSION RESUMED
===================================================================

 Source: HANDOFF.json (created: <timestamp>) [STALE WARNING if applicable]
 Branch: <branch> (base: <base_branch>)

 Task: <task_summary>

 Completed:
   - <completed item 1>
   - <completed item 2>

 Remaining:
   - <remaining item 1>
   - <remaining item 2>

 Blockers: <blockers or "None">

 Key Decisions:
   - <decision>: <reasoning>

 Uncommitted Work: <N file(s)> [WARNING: N file(s) missing if applicable]

 False Completions: <N placeholder(s)> [or "None detected"]

 Next Action:
   <next_action description>

===================================================================
```

**GATE**: Status dashboard constructed. Ready to present to user.

### Phase 3: PRESENT

**Goal**: Show the user what was reconstructed and confirm before proceeding. Never skip the dashboard — it is the validation checkpoint that catches assumptions made by the new session before they cause problems.

**Step 1: Display status dashboard**

Show the dashboard from Phase 2.

**Step 2: Handle stale handoff warning**

If `stale_warning` is true, warn the user before proceeding (stale handoffs may describe work superseded by manual changes between sessions):
```
WARNING: Handoff is from <timestamp> (>24 hours ago).
State may not reflect manual changes made since then.
Proceed with this handoff or discard it? [proceed/discard]
```

If user discards, fall to next priority level in cascade.

**Step 3: Determine action mode**

- **Quick resume** (user said "continue", "resume", or similar with no qualifiers): Skip options menu and proceed directly to Phase 4 to execute `next_action`. This optimizes for the common case where the user trusts the handoff and wants to get back to work fast.
- **Review mode** (user said "what was I doing", "where did I leave off", or asked a question): Display dashboard only, wait for user to choose what to do next

**GATE**: User has seen the dashboard. In quick resume mode, proceed to Phase 4. In review mode, wait for user direction.

### Phase 4: EXECUTE

**Goal**: Route to the next action and clean up handoff files (they are ephemeral session artifacts, not persistent state, so keeping them risks future `/resume-work` calls loading outdated context).

**Step 1: Execute next action**

Take the `next_action` from the handoff and execute it:
- If it matches a skill trigger (e.g., "run tests" -> /vitest-runner), invoke that skill via the `/do` routing system for proper agent/skill selection
- If it describes a code change, proceed with the implementation directly
- If it requires user input (e.g., "need clarification on threshold"), present the question

Carry forward all context from the handoff: decisions made, approaches rejected, gotchas to avoid. Honor previous session's findings unless circumstances have changed — reexploring rejected approaches burns context on work already done.

**Step 2: Clean up handoff files**

After the next action has been initiated (not necessarily completed — just successfully started), delete the one-shot handoff artifacts to prevent stale state:

```bash
# Remove one-shot handoff artifacts
rm -f HANDOFF.json .continue-here.md
```

If `--keep` flag was provided, skip deletion (use only for debugging).

**Step 3: Update task_plan.md if present**

If `task_plan.md` exists, update its status line to reflect that the session has resumed. The plan is the persistent record; handoff is the ephemeral session context:
```
**Status**: Resumed from handoff — executing: <next_action summary>
```

**GATE**: Next action initiated. Handoff files cleaned up. Session is now in active work mode. Note: This skill never modifies code, resets git state, or discards uncommitted changes — it only reads and deletes handoff files.

---

## Error Handling

### Error: No State Sources Found
**Cause**: No HANDOFF.json, no .continue-here.md, no task_plan.md, and git log is empty or on a fresh branch
**Solution**: Inform user: "No session state found to resume from. Use /do to start a new task, or describe what you were working on and I'll reconstruct manually."

### Error: HANDOFF.json Parse Failure
**Cause**: HANDOFF.json exists but contains invalid JSON (corrupted, partially written, manually edited badly)
**Solution**: Warn user about the parse error. Fall through to .continue-here.md if it exists, otherwise fall to task_plan.md. Do not silently ignore the error — the user should know their handoff was corrupted.

### Error: Uncommitted Files Missing
**Cause**: Handoff reports uncommitted files that no longer exist (worktree cleanup, manual deletion, git checkout)
**Solution**: Alert the user with specific file names. These changes are likely lost. The user may need to recreate them — the handoff's `context_notes` and `decisions` can help guide reconstruction.

### Error: Stale Handoff Rejected
**Cause**: User chose to discard a stale (>24h) handoff
**Solution**: Delete the stale handoff files and fall through to the next priority level in the cascade (task_plan.md or git log). Proceed with the lower-quality reconstruction.

---

## References

### Related Skills
- `pause-work` — Creates the handoff artifacts this skill consumes
- `do` — Routes next_action to appropriate agent/skill for execution
- `workflow-orchestrator` — For complex multi-phase tasks that benefit from handoff between phases