When a task spans multiple sessions, context is lost between them. Handoff documents bridge that gap.
The Pattern
Before ending a long session:
Create a handoff document summarizing:
- What we accomplished
- Key decisions and why we made them
- What didn't work (so the next session doesn't retry)
- Remaining work
Save it as HANDOFF.md in the project root.Then in the next session:
Read HANDOFF.md and continue where we left off.What to Include
A good handoff captures things that aren’t obvious from the code:
- Decisions: “We chose Zustand over Redux because…”
- Failed approaches: “Tried using WebSockets but hit CORS issues with the proxy”
- Architecture context: “The new auth flow needs to work with both the mobile and web clients”
- Remaining tasks: Specific, actionable items
Automate It
Create a custom slash command at .claude/commands/handoff.md:
Summarize the current session into a handoff document.
Include: accomplishments, key decisions (with reasoning),
failed approaches (with why they failed), and remaining work.
Save to HANDOFF.md.Then just type /handoff before ending any session.
Tip
Delete HANDOFF.md once the work is complete. It’s a temporary artifact, not documentation.