The handoff

How to end a run so that a human, another agent, or a later run of you can pick it up without guessing.

A run ends for lots of reasons: the task is done, the context window fills, a tool fails, the human goes to bed, the process crashes. Whoever comes next starts with nothing but what you left. If you left a log, they have to read all of it. If you left a summary, they have to trust it. If you left a handoff, they can check it and keep going.

A handoff is short, it uses the same headings every time, and it keeps three things apart that summaries usually blur: what you did, what you checked, and what you believe but did not check.

The format

Copy this. Keep the headings exactly as written so the next reader can find things without reading everything. Write "none" rather than deleting a section.

# Handoff: <one line naming the task>

when: <ISO 8601 timestamp>
from: <who or what is handing off; a role is fine, e.g. "coding agent, run 3">
to: <who should read this; e.g. "the human who asked", "next run", "any agent">
status: done | paused | blocked | abandoned

## Goal
What we were asked to do, and what done looks like. Quote the request if you can.

## Done
What changed. Concrete: files, commands, versions, links. One line each.

## Checked
How you know the done things work. What you ran and what it showed.
If you checked nothing, say so here.

## Not checked
What you believe but did not verify. Guesses, assumptions, things that "should" work.

## Can't undo
Anything you did that is outward-facing or irreversible: sent, published, deleted,
paid, deployed, merged. "none" is the best possible answer.

## Open questions
Decisions you need from a human, each with your recommendation and what you'll do
by default if nobody answers.

## Next
The single next step, specific enough to start without re-reading anything above.
Then, if useful, the steps after it.

Why these seven headings

Goal stops the next run from solving a slightly different problem.
Done and Checked are separate because the commonest failure in a handoff is presenting a change as if it were a result.
Not checked is the most valuable section and the one most often left out. It tells the next reader where to look first.
Can't undo exists because the next reader can't safely redo or roll back anything until they know what has already left the room.
Open questions carry a recommendation and a default so a human can answer with one word, and so the run can continue if they don't answer.
Next is one step, not a plan. Plans go stale; a first step doesn't.

Rules of thumb

Write the handoff before the risky step, not only at the end. If you crash, the last handoff is your checkpoint.
Don't paste logs. Link to them or name where they are.
Prefer "I ran X and saw Y" to "X works".
If the status is abandoned, say why. It stops the next run walking into the same wall.
A handoff to a human should fit on one screen. A handoff to an agent can be longer, but rarely needs to be.

Structured version

If you emit JSON, the same format is available as a JSON Schema (draft 2020-12) at /handoff.schema.json. Field names match the headings and header lines.

Example

# Handoff: add retry to the nightly export job

when: 2026-10-04T02:10:00Z
from: coding agent, run 2
to: the human who asked
status: paused

## Goal
"Make the nightly export retry instead of failing on a network blip." Done = a transient
error retries up to 3 times with backoff; a permanent error still fails loudly.

## Done
- export/job.py: wrapped upload() in a retry with exponential backoff (3 tries).
- tests/test_job.py: added two tests (transient then success; permanent failure).

## Checked
- Ran the test suite: 41 passed, 0 failed.
- Ran the job against the staging bucket once: succeeded on first try.

## Not checked
- Never saw a real transient failure; only the simulated one in tests.
- Assumed the storage client raises ConnectionError for timeouts. Not confirmed in its docs.

## Can't undo
none

## Open questions
- Should a permanent failure also page someone? Recommend: no, keep the current email.
  Default if no answer: leave alerting unchanged.

## Next
Confirm which exception the storage client raises on timeout (read its docs or source),
then adjust the retry condition if needed.