Handover

handover

The problem this solves: a long Claude Code session ends, and everything it learned evaporates. The next session starts cold and re-derives context you already paid for. But the fix people reach for - dumping the whole session into a running log - is worse, because now the next session has to read 300 lines to find the 5 that matter.

This skill draws one line: what does the NEXT session actually need to resume, and nothing else. Everything durable gets routed to a permanent home instead. What's left is a short, disposable note that gets overwritten every run and never accumulates.

Designed for stateful, multi-session work - the kind where you're mid-build across several sittings and the state doesn't fit in your head.

Configure once

The skill routes durable knowledge out of the handover and into permanent stores. Point these at wherever yours live (edit this block, or tell the session at runtime):

MEMORY_STORE  = ~/.claude/  (or your Claude Code memory directory)
KNOWLEDGE_BASE = (optional) a wiki, notes vault, or docs folder for
                 world-state and cross-project decisions

If you don't keep a separate knowledge base, fold that routing into memory. The principle holds regardless of where the stores physically are.

Step 0 - Confirm there's anything to hand over

If git is clean, nothing is half-finished, and no decision/constraint/open question surfaced this session, tell the user there's nothing to hand over and stop. Do not write an empty HANDOVER.md. A self-contained session whose output already landed somewhere durable does not need a handover.

Step 1 - Survey what actually happened

• git status (uncommitted changes, untracked files)
• git log since the session started (commits made this session)
• git diff --stat for a sense of what moved
• Note tasks marked done vs. still in-flight this session

Do this by reading real state. Do not reconstruct from memory.

Step 2 - Separate the load-bearing 5% from noise

Identify, for the NEXT session:

• Shipped: commits, deploys, merged work
• In-flight: half-finished work, with enough context for a cold reader
• Watch-outs: footguns hit, surprising state, broken assumptions, fragile spots
• Open questions: decisions parked for the user

Ignore pure execution noise (routine edits, things fully completed and committed).

Step 3 - Route durable knowledge to the right home (NOT the handover)

This is the step that keeps a handover from turning into a junk drawer.

• Durable fact / rule / preference (true beyond this session) → your memory store. Update an existing entry rather than duplicating.
• World-state / project snapshot / cross-project decision → your knowledge base, if you keep one. Just record it; don't reorganize.
• Per-project decision → memory.

Only write what future-you actually needs. Do NOT log daily activity into either store.

Step 4 - Offer to commit (ask first)

If there are uncommitted changes worth committing, summarize them and ask before committing. Never commit without confirmation. If the user declines, the uncommitted state goes into the In-flight section so it isn't lost.

Step 5 - Write HANDOVER.md (overwrite)

Write to <repo-root>/HANDOVER.md. It is disposable, not a log - but "disposable" means resolved items get dropped, not that you blindly clobber. Before writing, READ any existing HANDOVER.md and carry forward any in-flight item, watch-out, or open question that is still unresolved. Only drop what's genuinely done. If two or more independent workstreams are live at once, keep them in separate labelled threads rather than flattening them into one list.

# Handover - <repo name>
_Last session: <YYYY-MM-DD>_

## Shipped this session
- <commit / deploy / merged work, terse>

## In flight
- <half-finished work + enough context for a cold reader to resume>

## Watch-outs
- <gotchas, surprising state, broken assumptions, fragile spots>

## Open questions
- <decisions parked for the user>

Keep each section to the essential lines. Empty a section to - (none) rather than padding it. Total length: readable in under 30 seconds.

Step 6 - Wire the read-side (first run in a repo only)

The next session must auto-read HANDOVER.md. Ensure the repo's CLAUDE.md contains the reference below. If CLAUDE.md doesn't exist, create it with this content. If it exists but lacks the line, append the block. Skip if already present.

## Session start
At the start of each session, if `HANDOVER.md` exists at the repo root, read it
first - it holds in-flight state, watch-outs, and open questions from the last
session. Act on it, then overwrite it via /handover at session end.

Step 7 - Print the handover to chat

Print the four-section note in chat so the user sees it without opening the file. State plainly what you routed to memory / knowledge base and what (if anything) you committed.