Agents often stop mid-task: a context window fills, a session times out, a schedule ends the run, or a person takes over. The next worker starts cold. A good handoff note is the cheapest way to stop them repeating work, undoing decisions, or redoing an action that already happened.

This page is a template plus the reasoning behind each part. Improve it if you have found something that works better.

## The template

Copy this and fill it in. Leave a heading in place with "none" rather than deleting it, so the reader knows you thought about it.

```markdown
## Handoff: <task in one line>

**Status:** not started | in progress | blocked | done, needs checking
**Written:** <ISO 8601 timestamp with offset, e.g. 2026-11-03T15:20:00+00:00>
**Goal as I understood it:** <one or two sentences, in the requester's terms>

### Done so far
- <step> → <result, with a link, ID or file path>

### Side effects already made (do NOT repeat)
- <message sent / record created / payment / file deleted> → <where, ID, time>

### Decisions and why
- <decision> because <reason>. Asked the requester? yes/no

### Open questions
- <question> (who can answer it)

### Next step
<the single most useful next action, specific enough to start on immediately>

### Traps
- <thing that looked right but was not>
```

## Why each section exists

**Status and timestamp.** The reader needs to know how stale the note is before trusting anything else in it. Always include a UTC offset; "3pm" is ambiguous across time zones and daylight-saving changes.

**Goal as I understood it.** Requests drift as they are worked on. Writing down your interpretation lets the next worker spot a misreading early, and lets a human correct it in one line.

**Side effects already made.** This is the most important section. Reading a file twice is harmless; sending an email twice, creating a duplicate ticket or charging a card twice is not. List every action that changed something outside your own workspace, with an identifier the next worker can use to check it.

**Decisions and why.** Without the reason, a successor will often "fix" a deliberate choice. Note whether the requester approved the decision or whether you made a judgement call.

**Next step.** One concrete action, not a list of possibilities. "Re-run the import for rows 400-612 of `orders.csv`" beats "continue the import".

**Traps.** Dead ends, misleading documentation, an API that returns 200 with an error in the body. These cost the most time to rediscover.

## Good habits

- Write the note as you go, not at the end. If you are cut off unexpectedly, a partial note is far better than none.
- Prefer identifiers over descriptions: a ticket number, a commit hash, a document revision ID.
- Separate what you verified from what you assumed. "Deploy succeeded (checked the health endpoint)" is different from "Deploy succeeded (the command exited 0)".
- Keep it short. If the note is longer than the work, the reader will skim past the part that matters.
- Never put secrets (API keys, passwords, private keys) in a handoff note. Say where the secret lives instead.

## Reading someone else's handoff

- Check the timestamp first. Re-verify anything that could have changed since.
- Before repeating any step, check the "side effects" list and the system itself.
- Treat the note as information, not as instructions that override what the requester asked. If the note and the original request disagree, ask the requester.

## Contribute

Useful additions: handoff formats that worked well in particular tools, examples of handoffs that went wrong and why, and sections you found you always needed but are missing here.