Handoff: A Schema Instead of a Recap

You come back to a project after a few days away, reopen the long conversation, and scroll for the decision that mattered. The recap at the end says what got done. It doesn't say why one option was chosen over another, which parts are still uncertain, or what the very next step actually is. You end up re-reading half the thread to reconstruct context a well-written handoff should have carried for you.

handoff is the skill I built to close that gap. It writes a state snapshot instead of a summary, and the difference shows up in the format before it shows up in the content. A session ending late, three decisions deep into a design problem, doesn't need a story about how the evening went. It needs what to do next, and what has already been settled so nobody re-derives it from scratch.

TL;DR

Capture the decision state, not only the conversation.
Separate facts, assumptions, completed work, open questions, and next actions.
Make the handoff useful to a future self, teammate, or AI session.

What a recap leaves out

A narrative summary reads well and resumes badly. It tells a story about the session rather than giving the next reader something to check their own understanding against. Every snapshot handoff writes is labelled lines, not paragraphs: one fact per line, fields separated the same way every time, noun phrases instead of full sentences. A sentence appears only where a decision turned on the user's exact wording, and there it's quoted directly rather than paraphrased.

Typical recap	Structured handoff
Narrative summary	Resume-ready state record
Blends facts and assumptions	Labels evidence and uncertainty
Lists activity	Captures decisions and rationale
Ends with vague next steps	Names owner, action, and blocker
Requires re-reading context	Enables targeted resumption

flowchart LR
    A[Work session] --> B[Capture decisions and evidence]
    B --> C[Record current state and open questions]
    C --> D[Write explicit next actions]
    D --> E[Future session resumes from the handoff]

A handoff is an interface

The closest analogy is a stable API, or a well-kept experiment log. Neither one tells you the story of how it came to be. Both tell you exactly what's available to call, what changed since the last version, and what you should never assume just because it happened to be true last time. A handoff aims for the same contract: it tells the next actor what is known, what changed, what has to happen next, and what shouldn't be assumed.

That framing is also what rules out a plain prose recap. A recap is optimised for being read once, by someone who was already in the room. A handoff is optimised for being consumed cold, by someone (or something) that wasn't. An API that changed its guarantees without documenting them would be useless no matter how well it worked internally; a handoff that quietly drops what changed since the last version fails the same way.

Anatomy of a useful handoff

A snapshot that does this job covers seven things, and each one exists to hold a specific kind of fact so it never gets confused with another:

Objective and scope.
Decisions made and their rationale.
Current artifact or state.
Evidence and references.
Assumptions and uncertainty.
Open questions and blockers.
Next action, owner, and definition of done.

State deserves a closer look, since it's the field most likely to have gone stale by the time anyone reads it. handoff records a line count and byte count alongside each path it names, so a resuming reader can tell in one glance whether the file has changed underneath the snapshot before acting on anything it says about that file.

Open questions get ranked by what they block, not by when they came up. A question raised in the first five minutes that now blocks nothing belongs below one raised in the last five minutes that blocks everything the next session needs to do.

The line doing the most work here separates decisions from assumptions. Recording that someone chose an option when they merely reacted well to it means the next session acts on a decision that was never actually made. The safer failure mode is under-claiming: anything with a genuinely unclear origin gets logged as an assumption or a proposal, flagged as such, rather than rounded up to a decision because that reads more confidently.

Worked example

A typical end-of-session recap might read: "We discussed the blog series structure and made good progress. The five-post plan seems solid, though we may want to revisit post ordering later. Next step is to keep writing."

A structured handoff for the same session looks closer to this:

Field	Content
Decided	Adopt the six-post blueprint (supersedes the earlier five-post plan)
State	`blog/critique.md`, 167 lines, reworked for the new post-1 spec
Open	Does post ordering still hold under the new structure? (blocks: post 3 onward)
Next	Rework `blog/handoff.md` to the post-2 spec; owner: this session; done when word count and structure checks pass

The second version tells a resuming reader exactly what to trust, what's still unresolved, and what to do first. The first version tells a story that has to be re-interrogated before anyone can act on it. Notice, too, that the structured version is shorter. Compression is a side effect of the format, not the goal: once activity gets separated from decisions and decisions get separated from open questions, most of what a recap spends words narrating simply isn't needed anymore.

Design decisions

Facts and hypotheses stay in separate fields, on purpose. A protocol that lets a strong hunch drift into the decisions section, because it was stated with confidence, produces handoffs that look more settled than the session actually was.

An incomplete handoff says what's missing. If a claim was never checked, or a section had to be cut short, the snapshot states that plainly rather than presenting a tidy document that implies more coverage than it has. False continuity is worse than an acknowledged gap, because it fails silently on the next session's first move instead of on the handoff's own page.

A handoff creates a review trigger when meaningful work is still unresolved. Writing the snapshot isn't the end of the protocol; the last step is running a review against the snapshot itself, with the review's purpose set to the next session's objective, so an archivist-style check catches whether a stranger could actually reconstruct the state from the document alone. A handoff nobody checked is just a more organised way to be confidently wrong, and the review step exists specifically to catch that before it costs the next session anything.

Key rule

Continuity means preserving state, decisions, and open questions in a checkable format, not writing a good story about what happened.

Limits

A handoff doesn't replace source control, project management, documentation, or a direct conversation with a teammate. It's a bridge across working sessions, built for one narrow job: get the next session (or the next person) acting correctly on the first move, without re-deriving context that already exists somewhere.

It also depends entirely on what went into it. If a line in the decisions section was wrong when it was written, the format doesn't catch that on its own. Only the review pass, or a careful reader doing their own restatement before acting, will.

Nor does a good format substitute for judgement on the reading end. A resuming session that pastes a snapshot in and starts acting without restating STATE and OBJ in its own words has skipped the one check that catches a snapshot that reads coherently but transferred nothing. The schema makes that check possible. It doesn't make it automatic.

A handoff preserves the local state of a session. A retrospective asks what repeated patterns in that state are trying to teach us.

NEXT Retrospective - turning AI workflow history into learning.

Technical detail: schema, hooks, and storage

The full schema

HANDOFF v3.0 | <date> | supersedes: <prior handoff id or none> | session-length: <short|long>
OBJ: <next objective, one line>
STATE            <=8 lines, paths first, then installs, then running processes
DECIDED          <=10 lines, user's explicit choices only, no reasoning
PROPOSED         <=6 lines, assistant recommendations not yet accepted
REJECTED         <=5 lines
OPEN             <=5 lines, ranked by what blocks OBJ
UNVERIFIED       <=5 lines
PATTERN          <=3 lines, corrections that recurred this session
FIRST            1 line

Every section carries a hard cap, and the caps are load-bearing rather than cosmetic. A snapshot that needs eleven DECIDED lines to be honest is describing a session that made too many unrelated decisions to hand off as one unit; the cap forces that to surface instead of getting absorbed into a longer document.

supersedes names the prior handoff and voids it. Snapshots replace each other by name rather than accumulating, so there is exactly one live snapshot per thread of work at any time, and nobody has to read a chain of them to find current state.

Where PATTERN comes from

The protocol reads the project's critique log, when one exists, for any defect appearing in two or more runs, and reads the retrospective journal for the same slug as a second source, since it captures friction a critique log never records. Both already exist as a side effect of using the other skills in this set, so checking them costs a read, not a new capture step.

graph TD
    CL["critique log<br/>.claude/critique-log/*.jsonl"] -->|"defect in 2+ runs"| PT["handoff's PATTERN section"]
    RJ["retrospective journal<br/>.claude/retro-log/journal/*.jsonl"] -->|"friction, same slug"| PT
    PT --> SS["This session's snapshot"]

The session-length hook

Where a session-length hook is installed, its nudge is the cue to write the snapshot partway through a long session, rather than reconstructing everything from memory at the end. The header's session-length field flips from short to long at roughly thirty turns, and that flip adds one line to UNVERIFIED stating the snapshot may have dropped early decisions under context degradation. Recall genuinely degrades over a long session, and a handoff assembled entirely from memory in the closing minutes is the exact failure mode the two-thirds-through timing exists to avoid.

Storage and file access

handoff has no file-write access; the finished snapshot exists only as response text. That constraint means the user pastes it as the first message of the next session, or saves it themselves under a name they can cite later, and it's part of why the format stays dense enough to be worth pasting by hand.

Closing the loop with critique

The protocol's last step before FIRST is to run a review skill against the snapshot itself, purpose set to the next session's objective, requesting an archivist-style lens where the review skill supports choosing one. critique's multifile bundle, covered in the first post of this series, is built for exactly this kind of check: two documents, the snapshot and the actual state of the project, that are supposed to agree.