Handoff Documents — Institutional Memory Across Sessions
Long sessions accumulate context that new sessions don't have. Without a handoff document, the next session starts cold and repeats decisions already made. With one, it starts warm and continues from exactly where work stopped.
Quick Reference
- →Handoff doc: decisions made, work done, what failed (and why), next step
- →Write it: 'write a handoff doc and save to .claude/handoff.md before I close this session'
- →Start next session: 'read HANDOFF.md and continue from where the previous session stopped'
- →Auto-memory vs handoff docs: auto-memory = persistent learnings across all sessions; handoff = continuing a specific in-progress task
- →/recap as base: use /recap to generate the structured summary, then ask Claude to expand it into a full handoff doc
- →Team handoffs: handoff docs enable another developer's Claude session to continue your work
The Cold Start Problem
A three-hour debugging session accumulates enormous context: what was tried, what failed, why it failed, what the current theory is, what the next step should be. When you close that session, all of that context lives only in the conversation history.
When you start a new session the next day, you either resume the full session (loading a large context), or you start fresh and risk repeating the same dead ends. Neither is great for long, complex investigations.
A handoff document externalizes that context into a structured file — decisions made, approaches tried, what failed and why, the current theory, and the recommended next step. The next session reads one file and starts warm.