handoff
Handoff
Section titled “Handoff”A handoff doc exists to save the next reader (a fresh session, a different agent, or you tomorrow) from re-deriving everything this session already figured out. Write for someone with zero memory of this conversation, not a recap for someone who was watching.
What to include
Section titled “What to include”- Goal. One sentence: what this session was actually trying to accomplish.
- Done — verifiably. What’s complete, stated as a fact a reader can check (a commit hash, a passing test name, a file path with the final content) — not “implemented X” without a way to confirm it.
- In-flight / blocked. What’s partially done, and specifically why it stopped — a failing test with its actual output, a decision waiting on the user, an external dependency not yet available. “Ran out of time” without a concrete blocker is not useful to the next reader.
- Explicitly not done. Anything the goal implies but this session didn’t touch — cheap to state, expensive for the next reader to discover by assuming it’s covered.
- Next concrete step. Not “continue the work” — the literal next action: which file, which command, which decision needs making first.
- Decisions made and why. Only the ones that weren’t obvious — a constraint that ruled out the default approach, a tradeoff chosen deliberately. Skip anything a reader could re-derive from the diff itself.
Where it goes
Section titled “Where it goes”Don’t silently create or overwrite a tracked file. Ask where it belongs if
unclear, or default to an untracked scratch location (e.g. a HANDOFF.md at
the repo root, gitignored, or the session’s own scratchpad) — a handoff doc
is working state, not something that should land in a PR by accident.
Keep it short
Section titled “Keep it short”If the honest answer to “what’s done” is “everything, cleanly” — say that in one line and stop. A handoff doc’s value is proportional to how much re-derivation it saves, not its length.