handoff

---
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.md` exists 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:
1. Read its **Failed approaches** and **Known traps** sections. Carry forward entries still relevant and unresolved — re-tagged `[?]` unless re-verified in Step 2.
2. Move the file to `.handoffs/<ISO-timestamp>-handoff.md` (create the directory if needed).
3. If a `.gitignore` exists 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 `[?]`.

1. **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.
2. **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.
3. **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 `[?]`.
4. **No invention.** Can't verify it and don't clearly remember it? Omit it. An honest gap beats confident fiction.
5. 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

1. **Read HANDOFF.md fully** before doing any other work.
2. **Re-verify — the file may be stale or was written by a degraded model.** Run `git log`/`git status`/`git diff` against 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."
3. **Surface the Open questions** to the user. Do not guess past a blocked step.
4. **Confirm the plan.** Restate next steps adjusted for drift; get a go-ahead.
5. **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