| name | handoff |
|---|---|
| description | Use when ending or pausing a Claude Code session whose work must continue in a fresh session — user says "create a handoff", "write a handoff", "I'm ending this session", "prepare for a fresh session", "hand this off", or "/handoff" — or when starting a session in a project that already contains a HANDOFF.md at the root ("resume", "pick up where we left off", "continue from the handoff"). Also relevant when a session shows degradation symptoms — Claude contradicted an earlier decision, re-explored something already established, hallucinated file contents, or the user says the session "feels off", "is getting confused", or "context is running low". |
Handoff
Overview
Write (or resume from) a HANDOFF.md at the project root so a fresh Claude Code session can continue this work without repeating dead ends. The file is written for the next Claude session, not for the human.
Core principle: this skill runs when your memory is least reliable. Nothing goes in the file from memory alone — every claim is verified against the repo NOW, or explicitly marked as unverified.
Mode selection
HANDOFF.mdexists at project root AND this session did NOT just write it → RESUME mode- Otherwise → CREATE mode
Proactive suggestion rule
If you notice degradation (you contradicted an earlier decision, re-derived something already settled, misremembered a file), say ONE sentence — "This session may be degrading (⟨specific symptom⟩). Want me to run /handoff so a fresh session picks up cleanly?" — and STOP. Never write the file without confirmation.
CREATE mode
Step 1 — Archive any existing handoff
If HANDOFF.md exists at root:
- Read its Failed approaches and Known traps sections. Carry forward entries still relevant and unresolved — re-tagged
[?]unless re-verified in Step 2. - Move the file to
.handoffs/<ISO-timestamp>-handoff.md(create the directory if needed). - If a
.gitignoreexists and lacks.handoffs/, add it.
Step 2 — Verify BEFORE writing (anti-hallucination protocol)
Do this before drafting a single line. The rule: a claim may be tagged [V] only if confirmed by a command or file read during THIS handoff run. What you merely remember is [?].
- Orient in reality. Git repo: run
git status,git log --oneline -15,git diff --stat. No git: list the directories you believe you touched and re-read those files. Reconstruct what actually changed vs. what you believe changed. - Re-read, don't recall. Re-open every file the handoff will mention. Any quoted code or line number must come from the fresh read. File not where memory says? That's a caught hallucination — correct it, don't paper over it.
- Re-run ground truth. Run the project's test/build/lint command. "Tests pass" is written only from output produced in this run — otherwise it's
[?]. - No invention. Can't verify it and don't clearly remember it? Omit it. An honest gap beats confident fiction.
- If many claims end up
[?], write at the top: "Low-confidence handoff — verify aggressively."
Step 3 — Write HANDOFF.md
Copy assets/HANDOFF.template.md structure exactly. Fill every section; the template's HTML comments show what a good vs. useless entry looks like — read them, then delete them from the output.
Length budget: target ≤250 lines (~2,000 words); hard ceiling 400 lines. The handoff must fit in a fresh context alongside CLAUDE.md and initial exploration. Over budget? Cut in this order: drop narrative prose → compress Decisions to one line each → NEVER cut Failed approaches, Known traps, Verified state, or Next steps.
Quality gate — apply to every entry before keeping it: "Would a stranger with only this line avoid the mistake we made?" If not, add the file, the line, the reason, or delete the entry.
RESUME mode
- Read HANDOFF.md fully before doing any other work.
- Re-verify — the file may be stale or was written by a degraded model. Run
git log/git status/git diffagainst the SHA in the header; re-run the tests. Confirm each[V]claim still holds; resolve[?]claims if cheap. Report drift explicitly: "handoff said X, repo now shows Y." - Surface the Open questions to the user. Do not guess past a blocked step.
- Confirm the plan. Restate next steps adjusted for drift; get a go-ahead.
- Proceed. Leave HANDOFF.md in place — the next CREATE run archives it.
Rationalizations — all of these mean STOP
| Excuse | Reality |
|---|---|
| "I remember the session clearly, no need to re-verify" | This skill runs precisely because memory is degraded. Verify or tag [?]. |
| "Tests were passing earlier" | Earlier ≠ now. Re-run them or write [?]. |
| "A summary is enough — 'fixed several bugs'" | A stranger can't avoid a dead end from a summary. Which bug, which file, which failed approach first. |
| "Context is nearly full, skip verification to save tokens" | An unverified handoff poisons the NEXT session too. Verification is the non-negotiable part; cut prose instead. |
| "The old handoff is outdated, just delete it" | Archive it. Its dead-ends section may be the only record of what not to retry. |
| "I'll pad thin sections so the file looks complete" | Invention is worse than a gap. Write "not started, no design chosen" honestly. |
| "The user is in a hurry — auto-run the handoff" | Suggest, never auto-execute. One sentence, then stop. |
Red flags — catch yourself
- Writing a file path or line number you didn't re-read this run
- Typing "tests pass" without test output in this run's transcript
- An entry with no file reference and no specific reason
- HANDOFF.md creeping past 400 lines
- Resuming work without having re-run verification against the header SHA