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

   Replace the placeholder content with actual information from this session. Replace the --files and --tasks arguments with real values.

3. Confirm and continue — Then:
   • Autopilot mode (REMEMBRALL autonomous flag is active, or AUTONOMOUS MODE was mentioned in a recent nudge): Do NOT enter plan mode. Do NOT ask the user anything. Just say "Handoff saved" in one line and keep working on the next task. The handoff is a safety net — compaction will happen naturally and the session-resume hook will auto-inject it. This is the autopilot loop: save → keep working → compaction → auto-resume → keep working.
   • Attended mode, context is low (triggered by REMEMBRALL_WARN or REMEMBRALL_URGENT): call EnterPlanMode immediately. The session-resume hook will auto-inject the handoff after context clears. Do NOT tell the user to type /clear or /replay.
   • Manual invocation (context is fine): just confirm with a brief summary and continue working.

Rules

• Be concise but complete — the next instance has zero context
• Include file paths, not vague descriptions
• If there's an active task list, pass all pending tasks via --tasks
• Do NOT include raw code dumps — reference files and line numbers instead
• The handoff must be self-contained: another Claude reading only this file should be able to continue
• Only include files YOU modified this session in --files — not the user's other work
• Set --status to blocked if work is stuck, paused if intentionally stopping