pooriaarab Handoff
Verbatim entry from Matt Pocock's Dictionary of AI Coding,
dictionary/Handoff.md. Kept unedited on purpose — it is the shared vocabulary, not our house rules.The
./Name.mdlinks below are the source's own, left as-written so this stays a true copy. They resolve againsthttps://github.com/mattpocock/dictionary-of-ai-coding/blob/main/dictionary/, not against this repository.Our procedures live in the
handoffandclaude-handoffskills; this is the standard they are judged against.
Transferring agent context from one session to another. The carry mechanism varies — a written handoff artifact, an in-memory summary (compaction), and others. Distinct from clearing (no transfer at all). Reasons vary: switching roles (planner → implementer), kicking off an AFK run, fanning out to parallel sessions, or freeing up context window room.
The receiving session starts with zero context — the model is stateless, and nothing from the old session is visible to the new one. Whatever the next session needs has to be carried explicitly; everything else is gone. "No return path" is the constraint that shapes the carry: the new session can't ask the old one what it meant, so the carried material has to stand on its own.
| Mechanism | Form | Properties |
|---|---|---|
| Handoff artifact | File in the environment | You can read and correct it before anything depends on it; reusable across many sessions |
| Compaction | Summary in the context window | Automatic and cheap; harder to inspect; feeds one successor |
The visible failure of a bad handoff is relitigation: the new session re-opens decisions the old one had settled, because the carry recorded what was decided but not why. Judge a handoff by what a session with zero context could do with it.
Usage:
"Planning session is getting heavy — should I just keep going?"
"Do a handoff. Write the decisions to a doc, clear, start the implementation in a fresh session reading from it."
Applying it
The test. Read the handoff as if you had never seen the work. Can you take the next action without asking a question that has no one left to answer? If not, it is not finished.
Carry the why, not just the what. Relitigation is the failure mode, and it is caused by recording conclusions without their reasons. Every rejected alternative you do not write down is one the next session will re-propose. "Chose D1 over Postgres" invites the argument again; "chose D1 over Postgres because the Worker cannot hold a TCP pool" ends it.
Say what was tried and failed. A dead end that is not recorded gets walked again, at full cost. This is the highest-value line in most handoffs and the one most often left out.
Reference, do not duplicate. Point at issues, PRs, commits, plans and ADRs by number or path. A copy in the handoff is a second source of truth that starts drifting immediately.
Name what is in flight. Open PRs, running background jobs, an unpushed branch, a worktree with uncommitted work, a review waiting on a reply. Anything a fresh session cannot see by looking at main has to be stated.
Redact. The artifact may be committed, pasted into a prompt, or read by another account's agent. No keys, tokens, or personal data.
Picking a mechanism
- Written artifact when the decisions matter, several sessions will read it, or you want to correct it before anything depends on it. Use the
handoffskill. - Compaction when it is one successor, the work is mechanical, and nobody needs to audit the carry.
- Neither when there is genuinely nothing to transfer — that is clearing, and it is a valid choice, not a failed handoff.
Related
handoff— writes the artifact to a fileclaude-handoff— writes the summary and launches a background agent seeded with it