Handoff

The next reader has none of your context: not this conversation, not your terminal, not what you tried and dropped. Write so that someone with only the repository and the note can take the next step within minutes. Pair it with grill-before-build (its decision summary feeds the note) and backlog-item (for work nobody continues now).

When

• A session ends before the task is done: end of day, a usage limit, a context that is full.
• The work moves to another person, another department or another session.
• Before a long pause on a task.

Not needed when the task is finished and its report already says what works and what does not.

The note

1. State: one line (in progress, blocked, ready for review) and how far ("criteria 1-3 met, 4 not started"). Split what works and was verified from what is written but not verified.
2. Decisions made: each with the date, who decided and one line of why. Mark decisions the agent took on its own as its own; the next person may revisit those, not the ones a person made.
3. Open questions: each with who can answer it and your recommended answer.
4. Next step: the one concrete action to take first, with the command if there is one.
5. Where things are: branch, pull request, task, files touched, preview link, and the commands that reproduce the state.
6. Do not: approaches that failed and why, traps found, actions waiting for a human yes.

Before you write it

• Commit work in progress to the branch and make sure the next person can reach it. Changes left uncommitted on one computer are not handed off.
• Put the note where the next person looks first: the task or the pull request. Not only in a chat.
• No secrets, tokens or customer data in the note. Say where a secret lives ("the team password manager, entry 'staging database'"), never its value.

Example

State: in progress. Partial refunds: criteria 1-2 met and checked on staging; 3 (failed refund) written, not verified.
Decisions:
- 2026-10-02, billing lead: refunds stay in the order's currency; conversion is out of scope.
- 2026-10-03, agent (own call): amount field accepts two decimals; revisit if other currencies need more.
Open: should support see the refund reason field? (billing lead; recommend yes, read-only)
Next: run `npm test -- refunds`; two tests fail on rounding 0.005 amounts.
Where: branch `feature/partial-refund`, draft pull request "Partial refund on the order page", `src/orders/refund.ts`.
Do not: retry on timeout inside the handler; the provider may refund twice. Merging waits for the billing lead.

Receiving a handoff

1. Read the whole note and the task before changing anything.
2. Check the state yourself: get the branch, run the checks, open the preview. If it differs from the note, say so first and trust what you see.
3. Take the people's decisions as given. Reopen one only with a new fact, and name the fact.
4. Ask the open questions to the people named; do not guess the answers.
5. Say in the task that you have taken it, so the work is not done twice.
6. If a part of the note is missing, ask the author now, while they still remember.

Done when

Someone with only the repository and the note can start the next step without asking you anything.