Handoffs
Ending one session and starting the next without losing what mattered or carrying what did not.
A handoff is transferring context from one session to another, with no return path. The old session is gone. Everything that matters has to be in the artifact.
Handoffs are not a failure mode — they are the normal mechanism for work larger than one session. Done well they are an upgrade: the new session gets the conclusions without the exploration, the dead ends, or the debugging output.
The handoff note
At the end of a session that did not finish its ticket, write one. Have the agent draft it, then edit it — it will over-include.
We are stopping here. Write a handoff note for the next session, which will have none of this conversation. Include: - what is done and committed (with the commit SHA) - what is half-done, and exactly where - decisions we made this session and why - approaches we ruled out and why (so nobody retries them) - what to do next, as a concrete first action Be specific: file paths and function names, not summaries. Under 25 lines. Do not include exploration, debugging output, or anything already in the spec.
T3 handoff — 2026-03-11 Done (commit a3f91c2): findDueSchedules() in src/export/scheduler.ts, daily schedules only. Tests in __tests__/export/scheduler.test.ts cover daily + DST spring-forward. Half done: Monthly rules. The month-end case (31st in a 30-day month) is unresolved. Stub at scheduler.ts:88 throws NotImplemented. Decided: Month-end clamps to the last day of the month (not skip, not roll forward). Matches what the manual Monday export effectively did. Ruled out: date-fns rrule — pulls in 40kb and we only need three rules. Storing next_run_at on the row — goes stale when a timezone changes. Next action: Implement the clamp at scheduler.ts:88 and add the three month-end tests listed in the ticket. Nothing else.
Why "ruled out" is the most valuable section
A fresh session has no idea you already tried something. It will propose the discarded approach confidently, because it is the obvious one — that is often why you tried it first. Without this section, every handoff costs you the same argument again.
Handoffs between people, too
This artifact works identically for a colleague. That is a useful test of quality: if a teammate could pick it up from the note alone, an agent can. If they could not, neither can the agent — it will just pretend better.
Watch out
Do not paste the old conversation into the new session. It carries the noise you were trying to escape, it is enormous, and the parts that matter are already in the note. Handoff notes replace transcripts; they do not accompany them.
Try it
End your next unfinished session with a handoff note. Next day, start the fresh session with only the note, the spec, and the ticket. Note anything you had to re-explain — that is a missing section, and it will be missing next time too.
Takeaways
- Write a handoff note at every unfinished stopping point; keep it under 25 lines.
- Record ruled-out approaches with reasons, or they get retried.
- Be specific: paths, line numbers, commit SHAs.
- Never paste the old transcript into the new session.
What is the quality test for a handoff note?
Whether a competent colleague who was not there could continue from the note alone. An agent has strictly less context than that colleague and hides the gap better — so if a human would have to ask, the agent will simply guess.
A course by Pieter Zandbergen