handoff

Session Handoff

Create a structured handoff document that any Claude instance can read to resume this work.

Steps

1. Gather state — Review the current conversation to understand:

   • What task was requested
   • What has been completed so far
   • What remains to be done
   • Key decisions made and why
   • Files created or modified (collect the full list)
   • Current blockers or open questions
   • Test status (passing/failing)
   • Approaches tried that failed (with error messages)
   • Any task list items (check /tasks)
   • Active skill/workflow — If a skill was active (e.g., /plan-guarded, /bugfix, /refactor), note which skill and which phase/step the session was in

2. Write the handoff — Pipe a markdown document to handoff-create.sh. The script handles all path computation, git patches, YAML frontmatter, and team copies automatically. Always pass --session-id with $CLAUDE_SESSION_ID so the handoff can be found by auto-resume after /clear.

   REMEMBRALL_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cat /tmp/remembrall-meta/plugin-root 2>/dev/null)}"
   cat << 'HANDOFF_CONTENT' | bash "${REMEMBRALL_ROOT}/scripts/handoff-create.sh" \
     --cwd "$(pwd)" \
     --session-id "$CLAUDE_SESSION_ID" \
     --status "in_progress" \
     --files "file1.ts,file2.ts,file3.ts" \
     --tasks "Remaining task 1" "Remaining task 2" "Remaining task 3"
   # Session Handoff
   
   **Task:** [One-line description of what was requested]
   **Active Skill:** [Skill name if one was active, e.g., `/plan-guarded` Phase 2 step 3, `/bugfix` step 4 — or "none"]
   
   ## Completed
   - [Bullet list of what's done, with file paths]
   
   ## Next Step — Do This First
   [The EXACT next action. Not a list of everything remaining — just the single next thing to do. Be specific: "Run the test suite for auth module" not "continue testing". Include the file path and line number if applicable.]
   
   ## Remaining (after next step)
   - [Numbered list of what still needs to happen, in priority order]
   
   ## Failed Approaches
   - [Approaches tried and ruled out. For each: what was attempted, the exact error message or why it failed, and why it won't work. This prevents the next session from repeating the same dead ends.]
   
   ## Do NOT Do
   - [Things the next session must NOT do — files to leave alone, features that are done and should not be re-analyzed, rabbit holes to avoid]
   
   ## Key Decisions
   - [Important choices made and why — so the next instance doesn't re-debate them]
   
   ## Files Modified
   - [List of files changed in this session, with brief note of what changed]
   
   ## Context
   [Any important context the next instance needs — error messages, gotchas discovered, user preferences expressed during the session]
   
   ## Open Questions
   - [Anything unresolved that needs user input]
   HANDOFF_CONTENT