Session handoff

Session Handoff Playbook

Authored by Claude Fable 5. Context does not survive between sessions — the next model (or person) starts blind. A good handoff is the single highest- leverage thing you can write, because it's the difference between the next session resuming in one minute and re-deriving everything you already knew.

Why this exists

Left to improvise, models write handoffs that are either useless ("made some changes to the app") or a firehose (a diff dump nobody reads). The useful handoff sits between: it records the decisions and connections that aren't recoverable from the code itself, in language someone with zero context can follow. This playbook enforces that middle.

Phase 0 — Reconstruct the session honestly

Before writing, look back over what actually happened this session — not what you intended, what you did. Gather:

• What changed: files added/modified/removed. Check the actual diff or your edits, don't rely on memory of intent.
• Why: the decisions made and the reasoning. This is the part that's impossible to recover later — the code shows what, never why this over the alternative.
• What's unfinished: anything half-done, stubbed, or knowingly deferred.
• What broke or surprised you: dead ends, gotchas, things that didn't work the expected way. These save the next session from repeating your mistakes.

Be honest about incomplete or messy work. A handoff that hides the rough edges sends the next session walking into them blind.

Phase 1 — Read the existing log first

If a WORK_STATUS.md (or equivalent) exists, read its top section. You're appending to a running log, newest-on-top — match its format and voice, and update any "current snapshot" section at the very top so a reader gets the state of the world in the first ten seconds.

Phase 2 — Write the entry

Prepend a new entry (newest on top) in this structure. Write for a smart reader with zero context on this session — spell out names, don't assume they remember the codenames you invented mid-session:

## <Date> — <one-line session summary>

**What changed**
- <added/changed/removed, in plain language — file paths where useful>

**Why (decisions & reasoning)**
- <the choices made and what they were chosen over; the non-obvious calls>

**Connections**
- <what files/components/systems this touched and how they relate — the map
  the next session needs to not break something downstream>

**New components / patterns** (if any)
- <what was created, where it lives, and any rule it establishes for future work>

**Gotchas & surprises**
- <dead ends, things that didn't work as expected, things to not re-try>

**Open questions / next steps**
- <what's unfinished, what decision is pending, the obvious next move>

Then update the top-of-file snapshot (if the project uses one) to reflect the new current state.

Phase 3 — Quality check before finishing

Re-read your entry as if you're a developer who just opened the project cold. Ask:

• Could I resume the work from this alone, without reading the whole codebase?
• Do I understand why the key decisions were made, or just what happened?
• Are the next steps concrete enough to start on immediately?

If any answer is no, the entry is too thin — add what's missing. The test of a handoff is whether it eliminates the "wait, what were we doing?" that opens every uninformed session.

Phase 4 — Confirm

Tell the user the handoff is written and where, in one line. If the session also warrants a durable cross-session memory (a lasting project fact or preference, not just this session's log), mention that — but keep the two separate: WORK_STATUS.md is the running log, memory is for facts that outlive any one session.