Handoff

Handoff

Generate or resume from a structured handoff document that captures enough context for the next Claude Code session (or a human) to continue exactly where the previous session left off.

The handoff file is always: docs/HANDOFF.md in the repo root.

When to Use

• End of a work session
• Switching between roles or contexts mid-conversation
• Before closing a long-running session with unfinished work
• When the user says "handoff", "wrap up", "pass the baton", or similar
• Starting a new session from a previous handoff document
• When the user says "resume", "pick up where we left off", "continue from handoff", or similar

Mode Detection

There are no path arguments. The file is always docs/HANDOFF.md.

Generate Mode

Gathering Context

Collect the following information before generating the handoff. Use tools to gather what can be detected automatically; ask the user only for what cannot be inferred.

Auto-detect (do not ask the user)

1. Git branch -- run git branch --show-current
2. Working tree dirty? -- run git status --porcelain (any output = dirty)
3. Recent commits -- run git log --oneline -5 for recent context

Infer from conversation

4. Role -- what role has this session been operating in? (e.g., "developer", "content writer", "EOS facilitator", "researcher"). Default to "developer" if unclear.
5. Current work -- summarize what the session has been working on, in one or two sentences.
6. Status -- one of: in_progress | blocked | paused | ready_for_review | complete
7. Critical References -- 2-3 most important spec/design/plan docs referenced this session (omit section if none)
8. Recent Changes -- files modified this session with file:line-range references to key changes
9. Learnings -- patterns discovered, gotchas, root causes; prefer file:line-range references over inline code blocks
10. Artifacts -- exhaustive list of files/docs the next session should read to get up to speed
11. Next steps -- concrete, actionable items for the next session
12. Notes -- decisions made, trade-offs, links, anything else worth preserving

Ask the user (only if not inferrable)

If the role, current work, or next steps are ambiguous, ask a single clarifying question rather than guessing wrong.

Output Format

Generate the handoff as a fenced markdown block. Print it directly to the conversation first (do not write to file yet). After printing, ask the user to approve or amend it. Only write to docs/HANDOFF.md after user approval.

Prefer path/to/file.ext:line-range references over inline code blocks throughout.

---
handoff_date: YYYY-MM-DD
git_branch: {branch}
git_dirty: true|false
status: {status}
role: {role}
---
# HANDOFF: {Role} Session

## Current State

**Role**: {Role}
**Working on**: {CurrentWork}
**Status**: {Status}

**Git branch**: {branch}
{if dirty: "Working tree has uncommitted changes"}

## Critical References

- {path/to/spec.md} -- {one-line description}
- {URL or file} -- {one-line description}

(Omit this section if no critical references exist)

## Recent Changes

- `{file:line-range}` -- {what changed and why}
- `{file:line-range}` -- {what changed and why}

## Learnings

- {Pattern or gotcha discovered} -- see `{file:line-range}` for context
- {Root cause of a bug or decision} -- rationale: {brief explanation}

## Artifacts

Files and documents the next session should read to get up to speed:

- `{file path}` -- {why it matters}
- `{file path}` -- {why it matters}

## Next Steps

1. {step 1 -- specific and actionable}
2. {step 2}
3. ...

## Notes

{Decisions, trade-offs, gotchas, links -- anything that doesn't fit above}

---

*This handoff was generated automatically. Read the above carefully and continue where the previous session left off.*

Resume Mode

Three phases: Find & Read, Validate Environment, Orient & Ask.

Phase 1 — Find & Read

1. Read docs/HANDOFF.md -- this is always the file, no path scanning or arguments
2. If file not found, inform the user and switch to Generate mode
3. Parse YAML frontmatter: handoff_date, git_branch, git_dirty, status, role
4. Parse all markdown sections: Current State, Critical References, Recent Changes, Learnings, Artifacts, Next Steps, Notes
5. Read every local text file listed in ## Artifacts before proceeding to Phase 3. For each artifact, apply these rules:
   • Missing file: record as missing in the mismatch list and continue
   • Binary or unreadable file: record as unreadable and continue
   • Very large file (>500KB): sample the first and last 200 lines, note the truncation
   • URL: skip reading (treat as reference only); note it in the summary

Phase 2 — Validate Environment

Run these checks in parallel:

• git branch --show-current -- compare to git_branch from frontmatter
• git status --porcelain -- compare dirty state to git_dirty from frontmatter
• git log --oneline -5 -- check for new commits since handoff date
• Check if CLAUDE.md exists and read it (conventions may have changed)

Build a mismatch list from the results.

Phase 3 — Orient & Ask

Scenarios are evaluated in priority order — apply the first one that matches:

1. Complete -- status is complete:

   Inform the user: "The previous session marked this work as complete." Then ask via AskUserQuestion what they'd like to work on next.

2. Stale -- handoff_date is more than 7 calendar days ago (compare UTC dates, today − handoff_date > 7 days):

   Flag it: "This handoff is from {date} ({N} days ago) -- it may be out of date." Then ask via AskUserQuestion: "Should I trust this handoff and proceed, or re-explore the codebase first?"

3. Diverged -- current branch or dirty state doesn't match the handoff frontmatter:

   Surface each mismatch clearly, then use AskUserQuestion to ask how to proceed. Example: "Branch changed from feat/x to main. Should I switch back, or continue on main?"

4. Incomplete -- status is in_progress, blocked, paused, or ready_for_review:

   Acknowledge the status, surface any blockers noted, focus on completing the first unfinished step. Ask user to confirm before starting.

5. Clean -- none of the above apply:

   Present a brief summary ("Resuming as {Role} on branch {branch}"), list next steps from the handoff, and ask "Ready to start on step 1?" via AskUserQuestion.

Rules

Both modes

• Keep the handoff concise. The goal is fast onboarding, not a full session transcript.
• Omit sections with no content (e.g., skip Critical References if there are none).
• Next steps must be specific and actionable -- "continue implementing X" not "keep going".
• Do not include sensitive information (API keys, tokens, passwords).
• Prefer path/to/file:line-range references over inline code blocks.

Generate-specific

• Always print the draft to the conversation first and get user approval before writing to docs/HANDOFF.md.
• Create docs/ directory if it doesn't exist. Do this only after user approval, not during draft generation.

Resume-specific

• Never auto-execute next steps -- always confirm with the user first via AskUserQuestion.
• Read all local text Artifacts files before presenting the analysis; skip missing, binary, large, or URL entries (record them as noted in Phase 1).
• Treat next steps as suggestions, not commands -- the user may want to reprioritize.
• If docs/HANDOFF.md is not found, do not guess -- inform the user and offer to generate one.