Handoff

A fresh session knows nothing you didn't write down. The handoff's job is to transfer state and judgment, not narrative — what is true, what is believed, what is left, and where the traps are.

The one distinction that matters

Separate verified from believed everywhere. "The worker claims the row atomically (verified: drove the race, both orderings)" and "the email path should work (believed: not exercised)" are different classes of fact, and conflating them is how the next session ships the second one.

Structure

# Handoff: <work name> — YYYY-MM-DD

## Goal
One sentence. Plus the one-line status: on track / blocked on X / redirected.

## State
- DONE + VERIFIED: <each item, with how it was verified>
- DONE, NOT VERIFIED: <each item, with what verification is missing>
- IN PROGRESS: <the exact stopping point — file, function, half-written what>
- NOT STARTED: <remaining tickets/steps, in intended order>

## Decisions made (and why)
- <decision>: <the reason, and what was rejected>
Only decisions a resumer might otherwise re-litigate or accidentally reverse.

## Landmines
The expensive discoveries: the API quirk, the config gotcha, the test that
flakes if X. Each one here saves the next session an hour of rediscovery.

## Next actions
Ordered, concrete, first one small enough to start cold:
1. <action — file/command level>
2. ...

## Map
Files touched (with one-line roles), branch name, PR link, relevant
spec/tickets, launch command.

Rules

• Write for a reader with zero shared context; expand every "it" and "the fix".
• Landmines and decisions are the highest-value sections — spend the effort there, compress the rest.
• Durable facts (new domain terms, invariants, volatile external facts) belong in CONTEXT.md or tripwires, not only in the handoff — the handoff is read once; the docs are read every session.
• Save to docs/handoffs/YYYY-MM-DD-<name>.md, or paste directly into the next session's opening message.