Write the Handoff Before You Close the AI Session

The five minutes at the end of an AI coding session are worth more than the first twenty at the start of the next one. Not because the code needs those five minutes — it's already written, committed, working or not. It's because everything that isn't code — why you chose this approach over the other one, what you already tried and ruled out, what's still half-built — exists only in a conversation that's about to close. Once it does, that reasoning doesn't get remembered. It gets rediscovered, usually the hard way, usually by whoever opens the project next.

This is the third piece of a small habit system I use with AI coding assistants, alongside a project brief read at the start of a session and a file-based memory structure that keeps state and decisions between sessions honest. The handoff is the part that connects the two: it's the five-minute ritual, done right before you close the session, that turns what just happened into the record the next session — yours or a colleague's — actually reads.

Resuming a session is not the same as handing one off

It's tempting to skip this entirely on the assumption that modern tools already solve it. Claude Code, for instance, genuinely does let you pick a session back up: claude --continue reopens the most recent conversation in the current directory, claude --resume gives you an interactive picker across every session on the machine (searching the current project, its git worktrees, and then everywhere else), and you can name a session on creation so --resume auth-refactor finds it by name instead of a UUID. Cursor saves every chat thread automatically and surfaces them under "Previous Chats." These are real, useful features, and if you only need to keep working where you left off an hour ago, they're often enough.

They solve a different problem than a handoff does, though. What gets resumed is the raw transcript — every message, in the order you sent them, with no marker distinguishing the approach you shipped from the two you abandoned along the way. That's precisely the failure mode a written handoff exists to fix: a transcript is chronological, not curated. Skimming forty exchanges to reconstruct "wait, why did we rule out the queue-based approach" is exactly the tax a two-minute handoff note is meant to eliminate. And resume only works at all if you're in the same tool, on the same machine, within whatever retention window it keeps transcripts for — it does nothing for the teammate who inherits your branch, or for you three weeks and two context-window resets later when the session itself is long gone.

There's a broader data point behind why re-establishing context costs real time. In a 2025 randomized controlled trial, METR had experienced open-source developers complete real tasks on their own repositories with and without AI tool access, and found they were 19% slower with AI tools than without — despite believing, afterward, that they'd been roughly 20% faster. Among the factors METR identified was time spent establishing context with the AI about the specific codebase — the assistant, and the developer, both re-deriving things a five-minute note could have simply stated. The study is a snapshot of early-2025 tools and shouldn't be read as a verdict on AI coding assistants generally, but the mechanism it points at is exactly the one a handoff addresses: context re-establishment is a real, measurable cost, and it's one of the few costs in this workflow that's almost entirely avoidable.

What a handoff is actually for

If you're already keeping a CURRENT-STATE.md and a DECISIONS.md per the file-based memory approach, the handoff isn't a fourth document to maintain — it's the moment those two files get updated. Everything durable that happened in a session (what's now true, what got decided and why) belongs in those files; the handoff is simply the discipline of doing that update before closing, while you still remember the reasoning, instead of at the start of next time, when you don't.

Write it for a reader who wasn't in the conversation — because that's exactly who will read it. Sometimes that's you, three weeks from now, having long since forgotten why Redis got ruled out. Sometimes it's a colleague picking up your branch. Either way, the reader has none of the context that made your choices feel obvious at the time, which is precisely the information a transcript fails to preserve and a handoff exists to supply.

The five things worth writing down

Not every detail from a session earns a place in the handoff — that's what makes it different from a changelog. Five categories cover what actually saves the next session time.

Changed. What files or behavior are different now, described by purpose rather than by diff. "Auth middleware now issues short-lived rotating tokens instead of long-lived static ones" tells the next session what to expect; a pasted diff makes them reconstruct the why themselves, and git log already has the diff anyway.

Decided. The choice you made and the reasoning behind it — not just the what, but the constraint that made it the right call. "In-process cache over Redis, because we're running a single instance and don't need cross-instance session sharing yet" is a decision someone can safely revisit later, because it says exactly when it stops applying. "Used in-process cache" on its own is a fact with no expiration date, and it'll get silently violated the day someone scales horizontally.

Rejected. The approaches you tried and specifically ruled out, with the reason. This is the single highest-value line in most handoffs and the one most often skipped, because by the time you're wrapping up, the rejected path already feels irrelevant to you — you're not going back to it. But the next session doesn't have that instinct yet, and without this line, an AI assistant with no memory of the conversation, or a teammate who wasn't in it, will cheerfully propose the exact thing you already tried and watched fail, for the same reason it failed the first time.

State. What currently works, what's partially built, and what hasn't been touched. Precision matters more than optimism here: "token issuance works and is tested; refresh does not yet handle clock-skew or already-expired tokens" is something the next session can act on immediately. "Auth is mostly done" is not — it invites either redoing finished work or, worse, trusting broken work as finished.

Next. One specific, concrete action — not a list. "Write the test for refresh against an already-expired token" tells the next session exactly where to start. Three or four bullet points of "things to consider" reads more like a to-do list than a handoff, and a to-do list doesn't tell anyone which item to open the session with.

Example — a real handoff, five sections, under a minute to read:

Changed: Auth middleware now issues short-lived rotating tokens (src/middleware/auth.ts), replacing the static long-lived token. Decided: Token cache is in-process, not Redis — we run a single app instance and don't need cross-instance session sharing yet. Revisit if we scale horizontally. Rejected: Redis-backed sessions. Added an operational dependency (a service to run, monitor, and patch) we don't need at current scale. State: Token issuance works and is covered by tests. Refresh does not yet handle clock-skew or an already-expired token — currently throws an unhandled exception. Next: Write the failing test for refresh-with-expired-token first, then make it pass.

Five lines, and the next session — human or AI — starts exactly where this one stopped, with no guesswork about what's safe to touch.

A prompt that writes the handoff for you

You don't have to compose this from scratch every time. Asking the assistant to draft it from the session it just had works well, provided you review what comes back rather than accepting it verbatim — an assistant summarizing its own session can flatter its own decisions or bury a rejected approach it would rather not dwell on. Something close to this, sent as the last message before you close the session, produces a draft worth reviewing in under a minute:

Before we close this session, write a handoff note for whoever
picks this up next — which might be me in three weeks, or a
teammate who wasn't in this conversation.

Use exactly five sections, each 1–3 sentences:

Changed — what's different now, described by purpose, not as a diff
Decided — choices made and the specific reasoning behind each
Rejected — approaches we tried and ruled out, and why
State — what currently works, what's partial, what's untouched
Next — ONE concrete action to start the next session with, not a list

Be specific and honest about State, including anything broken or
untested. Skip anything that isn't durable — one-off debugging,
dead ends we abandoned in the first minute, commentary. If a
decision reverses one we made earlier in this project, say what it
supersedes and why, instead of just stating the new choice.

Treat the output as a first draft. Trim anything that reads like narration rather than a fact worth keeping, and check the Rejected and State sections specifically — they're the ones most likely to come back thin, since they're also the ones an assistant has the least incentive to dwell on.

Where it goes

Commit it, in the repository, in the files that are already supposed to hold this information — not a chat app, not a personal notes tool, and not a wiki page nobody involved in the next session will think to open. If you're using the PROJECT-CONTEXT.md / CURRENT-STATE.md / DECISIONS.md structure, this is exactly the update that keeps those files true: Changed and State fold into CURRENT-STATE.md; Decided and Rejected get appended to DECISIONS.md, never overwriting an earlier entry — superseding it with a dated note instead, the same append-only discipline that file already follows. Next doesn't need a permanent home at all; it just needs to be the first thing you (or the assistant) read when the next session opens, whether that's the top of your commit message or the first line you paste into the new session.

Keep the whole thing readable in under a minute. If it's taking longer than five minutes to write, it's drifting into changelog territory — cut it back to what the next session actually needs to not repeat your work.

What resume gives you, and what a handoff adds

They're complementary, not competing — resuming a session gets you back to the exact state of a conversation; a handoff gets a different session, possibly a different person, oriented in under a minute. Most real workflows benefit from both: resume when you're picking up your own thread within the hour, a handoff for everything that outlives the session.

Common mistakes

Writing it at the start of the next session instead of the end of this one. By then the reasoning behind a rejected approach has already faded, and you're reconstructing from a stale transcript instead of recording it fresh.

Letting it become a changelog. A handoff explains decisions and state; a list of every file touched belongs in the commit history, which already does that job better.

Leaving out what didn't work. The rejected approaches are usually the most expensive thing to lose, because rediscovering "we already tried that" typically means watching it fail a second time before anyone believes it.

Accepting an AI-drafted handoff without reading it. The prompt above produces a good first draft, not a finished one — the State and Rejected sections are exactly where an unreviewed draft tends to go soft.

Listing three things to do next instead of one. A list defers the decision about where to start; a single concrete action makes it.

Frequently asked questions

Doesn't --resume or a saved chat thread make this unnecessary?

For picking up exactly where you left off, in the same tool, soon — often yes. It doesn't help a teammate who wasn't in the conversation, doesn't survive a switch to a different assistant, and doesn't distinguish an accepted approach from a rejected one in a forty-message transcript. A handoff is what makes the reasoning portable.

How long should a handoff actually take to write?

Under five minutes for a normal session. If it's taking longer, it's probably accumulating changelog detail that belongs in the commit log instead.

Should the assistant write it, or should I?

Either, but review it either way. Having the assistant draft it from the session (see the prompt above) is usually faster than writing from scratch, provided you check it rather than pasting it in unread — particularly the Rejected and State sections.

What if nothing meaningful happened this session — just small edits or debugging?

Skip it, or write one line. The habit is meant to save real re-explanation time, not to generate ceremony for sessions that don't need it.

Does this replace DECISIONS.md and CURRENT-STATE.md from the project-memory system?

No — it feeds them. The handoff is the moment those files get updated, done at the point in the session when you still remember why you made each call, not a separate document alongside them.

The five minutes that pay for themselves

None of this requires new tooling — just five minutes, spent at the right moment, writing down what an assistant with no memory of this conversation, or a colleague who wasn't in it, would need to not repeat your work or your dead ends. Skip it, and that cost doesn't disappear; it just moves to the start of the next session, where it's more expensive to pay and far easier to get wrong.