Mechanism: Session Handoff
One-sentence definition
A session handoff is a short structured summary — goal, what changed, verify state, open questions — passed to the next chat, colleague, or model so work continues without re-reading the entire thread.
The problem
You hit context limits, need a fresh tab, or escalate to a stronger model. You paste the last twenty messages. The new session re-litigates old decisions, re-opens closed questions, or misses that tests were already green on a different branch.
Long transcripts are high noise, low signal for continuation.
Symptoms:
- New chat repeats fixes already done
- Lost track of which slice of a feature is complete
- Colleague asks questions answered in agent chat they cannot see
- Escalation model starts from zero
How it works
End or pause a session with a handoff block (copy template):
Handoff — [task name] — [date]
Goal: [one line]
Scope fence: [paths in / out]
Done: [what merged or verified green]
Diff state: [branch name, key files changed]
Verify: [last command + result]
Open: [1–3 unresolved questions or next slice]
Do not: [constraints still in force]Next session starts with handoff + new goal if the job changed — not full chat export.
Session A ends
│
▼
Handoff block (written by human or agent)
│
▼
Session B starts with handoff only + fresh disclosureHandoffs bridge scope fences — close fence A, handoff, open fence B.
When to use it
- Context window filling mid-feature
- Switching model, mode, or human owner
- End of day with work in progress
- Split & conquer between slices
- Before asking a teammate to continue agent work
When not to use it
- Completed task with merged PR — link PR instead of handoff novel
- Handoff as substitute for git — branch and commits carry truth; handoff summarizes
- Pasting handoff + entire prior transcript — pick one
Failure modes
Transcript dump — 10k tokens of chat. Fix: Handoff template only.
Missing verify state — Handoff says “almost done.” Fix: Last command + pass/fail.
Stale handoff — Branch moved; handoff says old file list. Fix: Regenerate from git status and test run.
No open questions — False confidence. Fix: List real risks or next slice explicitly.
Handoff without constraints — New session expands scope. Fix: Repeat fence and negatives.
Minimal example
Context: Slice 1 (health response shape) done; slice 2 (bootstrap uptime) next.
Handoff — verbose health slice 1 — 2026-06-17
Goal: AC1–AC3 for response shape (see health.test.ts)
Done: Merged on branch feature/health-verbose; AC1–AC3 green
Diff: src/routes/health.ts, tests/health.test.ts
Verify: pnpm test -- health.test.ts — pass
Open: uptime always 0 when verbose=1 — slice 2 needs bootstrap.ts
Do not: legacy/**, Dockerfile, new depsNew chat for slice 2 starts with this block + slice 2 goal — not slice 1 history.
Done when: Session B makes progress without re-asking what slice 1 accomplished.
Tool instances (optional deep-dive)
Portable idea above; this section is tool-specific. Date: June 2026.
Cursor
- Ask agent: “Produce a handoff block for a new chat” before closing tab.
- Store handoff in issue comment, PR description, or
scratch/handoff.md(gitignored). - New Composer — paste handoff as message 1; add only progressive disclosure files for open work.
Other tools
Jira update, Slack thread summary — same artifact for humans and agents.
Related mechanisms
- Scope fence — handoff closes one fence, opens the next
- Escalation — Level 4–5 need handoff
- Progressive disclosure — handoff replaces history bloat
Try it yourself
Exercise: Write a handoff block for work in progress right now — even if you continue the same chat. Use the template.
You need: Active task; three minutes
Done when: A stranger could continue with only the handoff + repo access.