handoff

Write a handoff document covering six sections: the goal in one sentence, verifiably done work with commit hashes or test names, in-flight items with concrete blockers, explicitly not-done scope, the literal next action, and non-obvious decisions with their reasoning.

Create a handoff before a session ends, before context-heavy interruptions like SSH or tmux disconnects, when context is running low, when a worktree passes to another worker or agent, or whenever explicitly asked for one.

Save handoff documents in an untracked scratch location such as a gitignored HANDOFF.md at the repo root or a session scratchpad. Never silently create or overwrite a tracked file, since handoffs are working state that should not land in a PR.

A useful handoff states completed work as checkable facts, names the specific blocker for anything in-flight, and gives the literal next action including which file, command, or decision comes first. Length matters less than how much re-derivation it saves.

A handoff only captures what the writer includes, so omitted decisions or unverified claims force the next reader to re-investigate. If everything finished cleanly, a one-line statement is sufficient and a long document adds no value.