resume-handoff · diff
v1.0.0 to v1.0.0
26 added, 305 removed. Audit B to B.
---
name: resume-handoff
description:
- "Resume work from a handoff document. **ALWAYS use when** the user says 'resume handoff', 'pick up
- where we left off', 'continue from handoff', or provides a handoff document path. Verifies current
- codebase state against handoff, validates changes, and creates an action plan."
+ "Resume work from a handoff document. **ALWAYS use when** the user says 'resume handoff', 'pick up where we left off', 'continue from handoff', or provides a handoff document path. Verifies current codebase state against handoff, validates changes, and creates an action plan."
disable-model-invocation: false
allowed-tools: Read, Bash, TodoWrite
version: 1.0.0
---
# Resume work from a handoff document
+ You are resuming work from a handoff document through an interactive process. Handoffs carry context, learnings, and next steps from a prior session that need to be understood and continued — never assume the handoff's state still matches the codebase; verify first.
+
+ ## Load on demand
+
+ | when | read |
+ | -- | -- |
+ | finding the handoff to resume from (no path given, path given, ticket given, or the cited path is missing on disk) | [`references/discovery.md`](references/discovery.md) |
+ | reading the handoff, verifying it against current state, and building the plan | [`references/process.md`](references/process.md) |
+ | deciding what to do given the codebase's divergence from the handoff | [`references/scenarios.md`](references/scenarios.md) |
+
## Prerequisites
```bash
- # Check project setup (thoughts, CLAUDE.md snippet, config)
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" ]]; then
"${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" || exit 1
fi
- # Auto-discover most recent handoff. Three-source waterfall:
- # 1. CATALYST_HANDOFF_PATH env var (CTL-484 continuation-worker contract —
- # set by orchestrate-revive's continuation branch when it spawns
- # `claude --bg --resume` after a turn-cap exhaustion).
- # 2. workflow-context.sh recent handoffs (interactive flows).
- # 3. (handled later in Step 4) interactive picker.
+ # Auto-discover the most recent handoff. CTL-2104: guard the discovered path — workflow-context.sh returns a REMEMBERED path, and a remembered path is exactly what goes stale (thoughts/shared is a per-project symlink). An unguarded read of a phantom path yields an empty document that reads like an empty handoff.
RECENT_HANDOFF=""
- HANDOFF_MISSING=""
- if [[ -n "${CATALYST_HANDOFF_PATH:-}" && -f "$CATALYST_HANDOFF_PATH" ]]; then
- RECENT_HANDOFF="$CATALYST_HANDOFF_PATH"
- elif [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
+ if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
RECENT_HANDOFF=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent handoffs)
fi
- # CTL-2104: guard EVERY path source, not just the env var. workflow-context
- # returns a remembered path, and a remembered path is exactly what goes stale —
- # `thoughts/shared` is a per-project symlink, so a path recorded in one worktree
- # can resolve to a different physical subtree here, and a sync that aborted may
- # mean the file never arrived at all. An unguarded read of a phantom path yields
- # an empty document that reads like an empty handoff.
if [[ -n "$RECENT_HANDOFF" && ! -f "$RECENT_HANDOFF" ]]; then
- HANDOFF_MISSING="$RECENT_HANDOFF"
+ echo "⚠️ Cited handoff is not on disk: $RECENT_HANDOFF"
+ echo " The channel is authoritative — recover from the last turn's text, see references/discovery.md."
RECENT_HANDOFF=""
- fi
- if [[ -n "$RECENT_HANDOFF" ]]; then
- if [[ "${CATALYST_IS_CONTINUATION:-}" == "true" ]]; then
- echo "📋 Continuation worker — resuming from CATALYST_HANDOFF_PATH: $RECENT_HANDOFF"
- else
- echo "📋 Auto-discovered recent handoff: $RECENT_HANDOFF"
- fi
- elif [[ -n "$HANDOFF_MISSING" ]]; then
- echo "⚠️ Cited handoff is not on disk: $HANDOFF_MISSING"
- echo " The channel is authoritative — recover from the last turn's text (see below)."
+ elif [[ -n "$RECENT_HANDOFF" ]]; then
+ echo "📋 Auto-discovered recent handoff: $RECENT_HANDOFF"
else
echo "⚠️ No recent handoff found in workflow context or filesystem"
fi
```
- ### When a cited handoff is missing on disk
-
- A broken citation is **not** lost work, and it is not a reason to stop. In every observed
- occurrence (CTL-2104) the content still existed — in a sibling project's `thoughts/shared`
- subtree, or on the writing host pending the next sync tick.
-
- 1. **The channel is authoritative.** Recover the handoff's substance from the last turns of
- the channel / ticket thread. That text is the record; the file is a convenience.
- 2. **Prefer an absolute path** when one was cited — `thoughts/shared` is a per-project
- symlink, so a *relative* citation is ambiguous across worktrees and may simply be
- resolving in the wrong tree. If you only have a relative path, search for the basename
- across the sibling subtrees before concluding it is absent.
- 3. **Never treat the missing file as lost work**, and never re-do landed work on that
- assumption — re-doing it is the more expensive failure.
-
- ## Configuration Note
-
- This command uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket
- prefix:
-
- - Read from `.catalyst/config.json` if available
- - Otherwise use a generic format like `TICKET-XXX`
- - Examples: `ENG-123`, `FEAT-456`, `BUG-789`
-
- You are tasked with resuming work from a handoff document through an interactive process. These
- handoffs contain critical context, learnings, and next steps from previous work sessions that need
- to be understood and continued.
-
- ## Initial Response
-
- Auto-discovery has already run in Prerequisites above. Check its output and follow this priority:
-
- 0. **If `CATALYST_IS_CONTINUATION=true` AND `CATALYST_HANDOFF_PATH` is set** (CTL-484
- continuation-worker contract from `orchestrate-revive`): the env-var hook in Prerequisites
- already selected the handoff. **Skip directly to Step 3 without prompting the user** — this is
- a background-dispatched continuation, not an interactive resume. Confirmation gates would
- hang the worker.
-
- 1. **If user provided a file path as parameter**: Use the provided path (user override). Skip to
- Step 3.
-
- 2. **If user provided a ticket number (like PROJ-123)**:
- - Run `humanlayer thoughts sync` to ensure `thoughts/` is up to date
- - Look in `thoughts/shared/handoffs/PROJ-123/` directory
- - List all handoffs for that ticket
- - If multiple exist, use the most recent (by timestamp in filename `YYYY-MM-DD_HH-MM-SS`)
- - If none exist, tell user and wait for input
- - Skip to Step 3
-
- 3. **If no parameters provided AND Prerequisites output shows a discovered handoff (📋)**:
- - Show user the discovered path
- - Ask: "**Proceed with this handoff?** [Y/n]"
- - If yes: use it and skip to Step 3
- - If no: proceed to option 4
-
- 4. **If no parameters AND Prerequisites shows no handoff found (⚠️)**:
- - List available handoffs from `thoughts/shared/handoffs/`
- - Show most recent 5 handoffs with dates
- - Ask user which one to use
- - Wait for user input with path or ticket number
-
- **STEP 3: Analyze the handoff**
-
- Once you have a handoff path:
-
- - Read the handoff document FULLY (no limit/offset)
- - Immediately read any research or plan documents it references
- - Do NOT use sub-agents to read these critical files
- - Ingest all context from the handoff
- - Propose course of action to user
- - Get confirmation before proceeding
-
- ## Process Steps
-
- ### Step 1: Read and Analyze Handoff
-
- 1. **Read handoff document completely**:
- - Use the Read tool WITHOUT limit/offset parameters
- - Extract all sections:
- - Task(s) and their statuses
- - Recent changes
- - Learnings
- - Artifacts
- - Action items and next steps
- - Other notes
-
- 2. **Spawn focused research tasks**: Based on the handoff content, spawn parallel research tasks to
- verify current state:
-
- ```
- Task 1 - Verify recent changes:
- Check if the recent changes mentioned in the handoff still exist.
- 1. Verify files mentioned in "Recent changes" section
- 2. Check if the described changes are still present
- 3. Look for any subsequent modifications
- 4. Identify any conflicts or regressions
- Use tools: Read, Grep, Glob
- Return: Current state of recent changes with file:line references
- ```
-
- ```
- Task 2 - Validate current codebase state:
- Verify the current state against what's described in the handoff.
- 1. Check files mentioned in "Learnings" section
- 2. Verify patterns and implementations still exist
- 3. Look for any breaking changes since handoff
- 4. Identify new related code added since handoff
- Use tools: Read, Grep, Glob
- Return: Validation results and any discrepancies found
- ```
-
- ```
- Task 3 - Gather artifact context:
- Read all artifacts mentioned in the handoff.
- 1. Read feature documents listed in "Artifacts"
- 2. Read implementation plans referenced
- 3. Read any research documents mentioned
- 4. Extract key requirements and decisions
- Use tools: Read
- Return: Summary of artifact contents and key decisions
- ```
-
- 3. **Wait for ALL sub-tasks to complete** before proceeding
-
- 4. **Read critical files identified**:
- - Read files from "Learnings" section completely
- - Read files from "Recent changes" to understand modifications
- - Read any new related files discovered during research
-
- ### Step 2: Synthesize and Present Analysis
-
- 1. **Present comprehensive analysis**:
-
- ```
- I've analyzed the handoff from [date] by [researcher]. Here's the current situation:
-
- **Original Tasks:**
- - [Task 1]: [Status from handoff] → [Current verification]
- - [Task 2]: [Status from handoff] → [Current verification]
-
- **Key Learnings Validated:**
- - [Learning with file:line reference] - [Still valid/Changed]
- - [Pattern discovered] - [Still applicable/Modified]
-
- **Recent Changes Status:**
- - [Change 1] - [Verified present/Missing/Modified]
- - [Change 2] - [Verified present/Missing/Modified]
-
- **Artifacts Reviewed:**
- - [Document 1]: [Key takeaway]
- - [Document 2]: [Key takeaway]
-
- **Recommended Next Actions:**
- Based on the handoff's action items and current state:
- 1. [Most logical next step based on handoff]
- 2. [Second priority action]
- 3. [Additional tasks discovered]
-
- **Potential Issues Identified:**
- - [Any conflicts or regressions found]
- - [Missing dependencies or broken code]
-
- Shall I proceed with [recommended action 1], or would you like to adjust the approach?
- ```
-
- 2. **Get confirmation** before proceeding
-
- ### Step 3: Create Action Plan
-
- 1. **Use TodoWrite to create task list**:
- - Convert action items from handoff into todos
- - Add any new tasks discovered during analysis
- - Prioritize based on dependencies and handoff guidance
-
- 2. **Present the plan**:
-
- ```
- I've created a task list based on the handoff and current analysis:
-
- [Show todo list]
-
- Ready to begin with the first task: [task description]?
- ```
-
- ### Step 4: Begin Implementation
-
- 1. **Start with the first approved task**
- 2. **Reference learnings from handoff** throughout implementation
- 3. **Apply patterns and approaches documented** in the handoff
- 4. **Update progress** as tasks are completed
-
- ## CLI Tools
-
- When you need to fetch ticket context from Linear (e.g., reading a ticket referenced in the
- handoff), use the Linearis CLI. For exact syntax, run `linearis issues usage` or see
- `/catalyst-dev:linearis` — **do not guess commands**.
-
- ## Guidelines
-
- 1. **Be Thorough in Analysis**:
- - Read the entire handoff document first
- - Verify ALL mentioned changes still exist
- - Check for any regressions or conflicts
- - Read all referenced artifacts
-
- 2. **Be Interactive**:
- - Present findings before starting work
- - Get buy-in on the approach
- - Allow for course corrections
- - Adapt based on current state vs handoff state
-
- 3. **Leverage Handoff Wisdom**:
- - Pay special attention to "Learnings" section
- - Apply documented patterns and approaches
- - Avoid repeating mistakes mentioned
- - Build on discovered solutions
-
- 4. **Track Continuity**:
- - Use TodoWrite to maintain task continuity
- - Reference the handoff document in commits
- - Document any deviations from original plan
- - Consider creating a new handoff when done
-
- 5. **Validate Before Acting**:
- - Never assume handoff state matches current state
- - Verify all file references still exist
- - Check for breaking changes since handoff
- - Confirm patterns are still valid
-
- ## Common Scenarios
-
- ### Scenario 1: Clean Continuation
-
- - All changes from handoff are present
- - No conflicts or regressions
- - Clear next steps in action items
- - Proceed with recommended actions
-
- ### Scenario 2: Diverged Codebase
-
- - Some changes missing or modified
- - New related code added since handoff
- - Need to reconcile differences
- - Adapt plan based on current state
-
- ### Scenario 3: Incomplete Handoff Work
-
- - Tasks marked as "in_progress" in handoff
- - Need to complete unfinished work first
- - May need to re-understand partial implementations
- - Focus on completing before new work
-
- ### Scenario 4: Stale Handoff
-
- - Significant time has passed
- - Major refactoring has occurred
- - Original approach may no longer apply
- - Need to re-evaluate strategy
-
- ## Example Interaction Flow
-
- ```
- User: /catalyst-dev:resume-handoff specification/feature/handoffs/handoff-0.md
- Assistant: Let me read and analyze that handoff document...
+ ## Configuration note
- [Reads handoff completely]
- [Spawns research tasks]
- [Waits for completion]
- [Reads identified files]
+ This skill uses ticket references like `PROJ-123`. Replace `PROJ` with your Linear team's ticket prefix — read it from `.catalyst/config.json` if available, otherwise use a generic `TICKET-XXX` form (`ENG-123`, `FEAT-456`).
- I've analyzed the handoff from [date]. Here's the current situation...
+ ## Invariants
- [Presents analysis]
+ - **Read the handoff document completely** — no `limit`/`offset` — and read every research or plan document it references, before proposing anything.
+ - **Never use sub-agents to read the handoff itself.** Sub-agents are fine for verifying the codebase state it describes ([`references/process.md`](references/process.md)).
+ - **Get user confirmation** before acting on the analysis, and again before starting implementation.
+ - **A missing handoff file is not lost work.** The channel/ticket thread is authoritative; recover from there rather than re-doing landed work ([`references/discovery.md`](references/discovery.md)).
- Shall I proceed with implementing the webhook validation fix, or would you like to adjust the approach?
+ ## CLI tools
- User: Yes, proceed with the webhook validation
- Assistant: [Creates todo list and begins implementation]
- ```
+ To fetch ticket context from Linear (e.g. a ticket referenced in the handoff), use the Linearis CLI — run `linearis issues usage` or see `/catalyst-dev:linearis` for exact syntax. Do not guess commands.