Guide · Context & Memory

How do you hand off work to a fresh Claude session?

Published 1 August 2026

Every long session ends the same way: the window is full, the model is drifting, and you start a new one. What you carry across that boundary decides whether the next hour is productive or spent re-deriving what you already knew. A handoff is not "paste the last few messages" — it is a written artefact, produced on purpose, that lets a model with zero history resume mid-task.

Why the naive handoff fails

The instinct is to summarise the conversation. That produces a narrative — "we tried X, then Y, then found Z" — which is the least useful thing you can give a fresh session. The new model does not need your history; it needs your current state. History is long, mostly obsolete, and full of abandoned approaches the model will happily retry.

The second failure is over-trusting the model to write its own handoff. Ask for "a summary so we can continue" and you get something confident and lossy: the decisions are there, the file paths are approximate, and the one blocking error is missing because it happened forty turns ago.

The five things a handoff must contain

  1. Goal, in one sentence. Not the epic — the thing that must be true when this task is done.
  2. Current state. What exists now, concretely: which files were changed and what changed in them. Paths, not descriptions.
  3. Decisions with their reasons. "Using integer minor units for money because rounding drift broke the totals test." The reason matters: without it, the next session relitigates the decision.
  4. Dead ends, explicitly named. "Tried the middleware approach — the framework runs it after auth, so it can't work." This is the highest-value section and the one always omitted. It stops the fresh session repeating an hour of your work.
  5. The exact next step. One action, small enough to start immediately. If you cannot name it, the handoff is not finished.

Add a sixth line whenever it applies: unresolved errors, verbatim. Paste the actual message and the command that produced it. Paraphrased errors are useless.

A template that works

## Goal
Invoice totals must match the ledger to the cent for multi-currency orders.

## State
- src/lib/money.ts — new Money type, integer minor units, 8 unit tests green
- src/features/invoice/total.ts — migrated to Money; 2 tests still failing
- migrations/ — untouched, schema still stores DECIMAL

## Decisions
- Integer minor units, not floats — float rounding broke the ledger test
- Conversion happens at the API boundary only, never in components
- Schema migration deferred until total.ts is green

## Dead ends
- Rounding at render time: totals then disagree with the stored value
- decimal.js: adds a dependency and does not fix the boundary problem

## Unresolved
- `bunx vitest run src/features/invoice/total.test.ts` → 2 failures,
  "expected 1999 to be 2000" on the JPY case (zero-decimal currency)

## Next step
Handle zero-decimal currencies in Money.fromMinor, then rerun that test file.

Roughly thirty lines. A fresh session reading it can act on the next step without asking a single orienting question.

Write it before you need it

The worst moment to compose a handoff is when the window is already full — the model has begun degrading, and its account of the session degrades with it. Two habits avoid that:

  • Keep it live. Maintain the handoff as a file in the repo from the start of the task and update it whenever a decision lands or a dead end closes. Then the handoff is always current and costs no extra model call at the boundary. It is not free in latency: a fresh session starts with a cold cache, so the first call pays full prefill on the whole new prompt — one reason to keep the handoff short rather than exhaustive.
  • Draft it at 70% of the window, not 95%. Ask for it while the model still has full command of the session, review it against what you remember, and correct it. The correction is the point — you are the only one who knows what was left out.

What not to carry over

A handoff is a filter, not an archive. Leave behind the turn-by-turn transcript, tool output that has already been acted on, code the model can simply read, and anything already captured in standing instructions. If a rule holds for every session in this repository, it belongs in your project's standing-context file, not in a handoff you rewrite every three hours.

Verifying the handoff before you trust it

One cheap check: open the fresh session, paste the handoff, and ask it to state the goal, the next step and one thing that has already been ruled out — before letting it touch anything. If any of the three comes back wrong or vague, fix the handoff rather than correcting the model in conversation. You will hand this document to another session in three hours.

Review checklist

  • Is the next step a single concrete action?
  • Are file paths exact, and errors quoted verbatim?
  • Does every decision carry its reason?
  • Are dead ends listed, so they are not retried?
  • Is anything in here that the model could just read from the code?

Where this fits

Session handoff sits in the Context & Memory part of the track, next to context budgeting and standing instructions. The underlying judgement is the same one every time: decide what has to survive a boundary, and put it somewhere the boundary cannot reach.

Related in this track

Keep going