Handoff

---
name: handoff
description: |
  Session handover: when context fills, a phase closes, or the topic changes, write an action-oriented handover
  to docs/SESSION_STATE.md, then recommend /clear.
---

# Session Handover (Handoff)

<!-- routing-eval reads this line; it lives in the BODY so the always-on skill LISTING stays inside
     Claude Code's budget (1% of the context window) — an overflowing listing gets descriptions
     truncated or dropped, which strips the very keywords a match depends on. -->
Trigger phrases: "handoff", "hand off", "session summary", "session state", "clear context", "I'll continue", "next session", "where we left off", "run out of room", "continue tomorrow"

## When
`/context` > 75% · phase closure · topic change. Goal: the next session should **not start from scratch**.

## Output (docs/SESSION_STATE.md, local)
```
# Session Handover — <date>
## Done
- <completed work + which files>
## In progress
- <what's half-finished + exactly where it was left off>
## Next step
- <a clear, single high-value step>
## Open decisions
- <pending decision + options>
## File pointers
- docs/PLAN.md, relevant modules...
## Blockers / risks
- <if any>
```

## Measure the session before summarising it
Run **`bash .claude/hooks/session-stats.sh`** first. What it reports belongs in the handover as fact, not
impression — an auto-compaction means state was already dropped before you started writing (say what was lost),
a runaway loop marks an approach the next session should not walk back into, and repeated prompts mark context
that never landed and has to be written down explicitly this time. Missing script (plugin install) → say so.

## Principles
- **Action-oriented:** focused not on "what was done" but on "exactly where to resume now."
- Preserve the rationale behind decisions (why this path was chosen) — so context isn't lost.
- Once written, start a fresh session with `/clear`.

## Holding a board item? The handover is not finished until the TEAM has it
`docs/SESSION_STATE.md` is gitignored — it survives your `/clear`, and nobody else can read it. So when a
`teamboard` claim is open, **the handover is not complete until it is on the board**. This is not an optional
extra step:
- Still on it → `board.sh note <id> "<where it stands, and why the rejected path was rejected>"`.
- Not coming back → `board.sh drop <id> "<same>"`, which puts it back in circulation with your context attached.
- Anything settled here that changes how OTHER items must be done → `board.sh decide "<what>" "<why + what it
  means>"`. A decision that stays in your transcript reaches nobody; on the board it reaches every teammate at
  their next session opening.

Write the board note FIRST, then the local file — an interrupted handover should lose the private copy, not the
shared one.

## Redaction (`<private>` marker)
`docs/SESSION_STATE.md` is a **shared, often committed** artifact — never persist a secret, token, credential, or
personal note into it. Any content wrapped in **`<private>…</private>`** is a redaction marker: strip it from the
written handover and leave a `[redacted]` placeholder in its place. If a resume genuinely needs a sensitive value,
point to *where it lives* (env var, secret manager, the person to ask) — never the value itself.

## Check it before trusting it
That DoD sentence is a claim about a file nobody has tested. Before closing, run the **cold-reader pass**: write
5–8 questions from the WORK (not from the file) with their expected answers, then answer them from the handover
alone. A question that cannot be answered is a gap in the file. Procedure, phrasing that keeps the test honest,
and the common failure shapes: **`references/cold-reader.md`**.

## DoD
- A handover file; a new session can resume where it left off by reading only this file.
- The cold-reader questions were written **before** the file and every one of them is answerable from it.