Resume Handoff

Complete handoffs: If the handoff has status: complete, this means the prior session wrapped up cleanly, NOT that the entire project is done, and NOT that claimed changes were actually written. The git diff check is mandatory even for complete handoffs. Read any linked plan documents to check for remaining work. ALWAYS present the full analysis and wait for user approval before taking any action, regardless of handoff status.

Mode 2: No Parameters

If no parameters provided, respond with:

I'll help you resume work from a handoff document. Let me find the available handoffs.

Which handoff would you like to resume from?

Tip: You can invoke this directly with a handoff path: `/resume-handoff thoughts/shared/handoffs/YYYY-MM-DD_HH-MM-SS_description.md`

Then wait for the user's input.

Process Steps

Step 1: Read and Analyze

1. Read handoff document completely:

   • Use the Read tool WITHOUT limit/offset
   • Extract all sections:
     • Tasks and their statuses
     • Recent changes
     • Learnings
     • Artifacts
     • Action items & next steps
     • Other notes.

2. Read artifact files directly.: Read all artifacts and critical files mentioned in the handoff:

   • Feature documents
   • Implementation plans referenced
   • Research documents mentioned
   • Files from the "Learnings" section completely
   • Files from "Recent changes" to understand modifications
   • Read any new related files discovered during research

   Use direct Read calls (not sub-agents) since handoffs typically reference well-defined file paths.

   Large files: If a Read call fails with "file content exceeds maximum allowed tokens," use grep -n "keyword" <file> to find relevant sections, then re-read with offset and limit parameters targeting those line ranges. Do NOT read the entire file — extract only what the handoff task requires.

3. Verify claimed changes. Run git branch --show-current and compare against the handoff's branch field. If they differ, flag the discrepancy in your analysis summary — the work may be on a different branch than the handoff recorded. Then run git diff HEAD -- <file> on each file listed under "Recent changes" to confirm the changes exist. Important: for brand-new files (created, not modified), git diff HEAD returns empty because they're untracked — this does NOT mean unimplemented. Follow up with git status -- <file> or ls <file> to confirm new files exist. Only treat an empty diff as "unimplemented" for claimed modifications to existing files. Also run git diff --stat HEAD to check for modifications NOT listed in the handoff — flag any unexpected changed files in your analysis summary. External files: Some files (e.g., MEMORY.md at ~/.claude/projects/) live outside the git repo. Before running git diff, check if the path is under the repo root. For external files, use test -f <path> && echo exists || echo missing or Read the file directly instead of git commands. Automated checks: If the handoff mentions automated checks or verification scripts (e.g., "13 automated checks pass"), run them to confirm the handoff's claims independently.

Step 2: Synthesize and Present

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]

For **external files** (paths outside the repo root — `~/`, `/tmp/`, `/Users/`): include an open/access command next to the artifact so the user can navigate immediately, e.g., `open ~/assets/file.html`. Also offer to move/copy the file to the repo root for easier access: "Shall I move this to the repo root for easier access?" Do NOT assume the user knows where external files live.

**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?

All sections above are required. If the handoff has no learnings, write "Key Learnings Validated: None in handoff." If no issues, write "Potential Issues Identified: None." Never skip a section.

STOP — ALWAYS wait for user approval here. NEVER proceed to Step 3 until the user explicitly confirms. This applies to ALL handoffs regardless of status (complete, incomplete, or ambiguous). Present the analysis, then stop and wait.

Exception — supplementary instructions as pre-authorization: If the user provided specific action commands in the invocation args (e.g., /resume-handoff path.md run launchctl bootstrap ...), those instructions constitute pre-authorization for those specific actions. In the analysis presentation, note "Proceeding with supplementary instructions as pre-authorized" and then continue without waiting for another explicit confirmation for those specific pre-authorized actions.

Labeling historical references: If the handoff document itself mentions paths to OTHER handoff documents (e.g., a prior session's handoff path listed under "Other Notes" or "Artifacts"), do NOT surface these as current artifacts. Label them explicitly as "(historical, from prior session)" or omit them entirely. Only list artifacts that are still actionable for the current session.

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]?
   

STOP — ALWAYS wait for user approval here. NEVER begin implementation until the user explicitly says to proceed. Do not interpret the absence of objection as approval.

Step 4: Begin Implementation

1. Always Read before Write: Use the Read tool on any file before calling Write or Edit on it — even if the path is known from the handoff context. This applies to ALL files, including files discovered during analysis that were not listed in the handoff. If an Edit fails with "File has not been read yet. Read it first before writing to it." OR "File has been modified since read", immediately re-read the file and retry the same edit.
2. Start with the first approved task
3. Reference learnings from handoff throughout implementation
4. Apply patterns and approaches documented in the handoff
5. Update progress as tasks are completed
6. Discover test paths before running: When verifying changes by running tests, find the test directory first rather than guessing. Use find . -name 'conftest.py' | head -5 or grep -r 'testpaths' pyproject.toml pytest.ini 2>/dev/null to locate the test root. Running pytest with a nonexistent path (exit code 4) cascades to any sibling parallel tool calls — discover first, then run.
7. Linting tools in parallel: When running ruff, flake8, mypy, or other linters alongside other Bash calls in a single message, append || true to prevent cascade failures. Linters use exit code 1 to mean "violations found" (not a process error), so a bare ruff check . in a parallel call will cancel all sibling tool calls if any violations exist. Use: ruff check transcript_pipeline/ || true.

Guidelines

Be thorough in analysis:

• Read the entire handoff document first
• Verify ALL mentioned changes still exist via git diff
• Check for regressions or conflicts
• Read all referenced artifacts
• Always Read before Write (all phases): Use the Read tool on any file before calling Edit or Write — even during verification, even for files with known paths. If an Edit fails with "File has not been read yet", immediately re-read and retry. Do NOT make opportunistic fixes during analysis (Steps 1-2) — add them to the todo list instead and execute in Step 4 after user approval.

Be interactive (NEVER skip approval gates):

• ALWAYS present findings and STOP before starting work
• NEVER proceed to implementation without explicit user confirmation
• Allow for course corrections
• Adapt based on current state vs. handoff state

Leverage handoff wisdom:

• Pay special attention to the "Learnings" section
• Apply documented patterns and approaches
• Avoid repeating mistakes mentioned
• Build on discovered solutions

Track continuity:

• Use TodoWrite to maintain task continuity
• Note the handoff path so the user can reference it when they commit. NEVER proactively suggest running /commit — the user will invoke it when they're ready.
• Document any deviations from the original plan
• Multi-phase plans: If the original handoff references a plan with remaining phases (e.g., "Phases 4-6 remain"), explicitly offer to create a new handoff at the end of Step 4 after completing the current phase. Say: "Phase N is complete. Phases X-Y remain. Shall I create a handoff for the next session?" Don't assume the user will remember — prompt them. Present this offer BEFORE any detailed verification checklists or lengthy artifact summaries so it is visible even when the final message is long.
• For single-phase or final-phase work, creating a handoff is optional but recommended if changes are substantial.

Pipeline routing:

• If the handoff's primary action items are approved plan revisions (iterate-type edits), invoke the /iterate skill with the plan path and the approved changes as feedback rather than executing the edits directly. The handoff content serves as the feedback input for Case A of the iterate skill.
• If the handoff's action items involve implementing a plan, and all plan phases are completed by the end of this session, suggest /validate {plan-path} as the next step to verify the implementation meets all plan criteria.

Validate before acting:

• Never assume handoff state matches current state
• Batch operation counts: If the handoff specifies an estimated count for batch work (e.g., "create 14 files", "process N items"), independently verify that count against the actual data source before starting. Handoff estimates are derived from snapshots that may not reflect current state — e.g., "19 - 5 existing = 14 new" is wrong if the 5 existing files are a different category than the 19 targets.
• Multi-phase plan drift: If the handoff describes future phases (e.g., "Phase 5: enrich-pipeline, ..."), verify those descriptions against the linked plan document. The plan file is the authoritative source -- it may have been modified after the handoff was created, making the handoff's phase descriptions stale. Always cross-check before treating handoff phase content as ground truth.
• Verify all file references still exist
• When checking for files that may not exist (checkpoint files, output CSVs), use test -f path && echo exists || echo missing rather than ls path
• When a Read call fails with "file does not exist" for a file referenced in the handoff, run git status -- <path> immediately to determine if it was recently deleted or renamed. A deleted-but-unstaged file can often be restored with git show HEAD:<path>.
• Check for breaking changes since handoff
• For destructive file operations (rm -rf, bulk deletes, file overwrites), present the command to the user for manual review. Do NOT execute directly.
• Live test substitution: When action items include "run manual tests of a skill" (e.g., "test /draft-outreach with X input"), substitute structural verification rather than executing the skill. Trace routing logic through SKILL.md, verify reference file consistency, count required table rows/sections, and check that names match across files. Orchestration skills trigger expensive multi-agent pipelines. Document each scenario as [SCENARIO]: structural check passed/failed — [brief trace summary].

Common Scenarios

Example Interaction Flow

User: /resume_handoff specification/feature/handoffs/handoff-0.md
Assistant: Let me read and analyze that handoff document...

[Reads handoff completely]
[Reads all referenced artifacts and files directly]

I've analyzed the handoff from [date]. Here's the current situation...

[Presents analysis]

Shall I proceed with implementing the webhook validation fix, or would you like to adjust the approach?

User: Yes, proceed with the webhook validation
Assistant: [Creates todo list and begins implementation]