rb17080 Session handoff
The next session starts with zero memory of this one. The handoff is the only thing that lets it pick up without re-deriving everything from scratch. Make it genuinely comprehensive - not a terse note, but the full story of the session, grounded in real git data rather than recall.
Write to HANDOFF.md at the repo root. This is live session state, so it is always gitignored - see "The file is always ignored" below.
Pull real data first, never recall
Before writing a word, gather ground truth. Recall drifts - the git log does not.
git logsince the last handoff: commit hashes and subjects. Do not paraphrase these from memory.git status: uncommitted or dirty files.- Current branch, and whether HEAD is pushed or ahead of origin.
- Read the existing
HANDOFF.mdif there is one, so you continue its timeline instead of starting over.
If it is the first-ever handoff (no file yet), or the repo has no commits, or HEAD is detached - say so plainly and work from whatever ground truth exists. Do not invent a history that is not there.
Match the project's voice, do not impose one
Read a few recent commit messages and any existing docs, and write the handoff in that voice. A handoff that sounds like the rest of the project reads as part of it; one in a generic assistant register reads as bolted on. The project sets the tone, not the skill.
Structure - use these sections, in this order
Session date and headline
The date, and a one-line headline of what this session was about.
What we did
A chronological narrative of the session - the actual sequence of what happened, picking up from where the last handoff left off. This is the "how we got here" thread: what got tackled first, what that led to, how it progressed. Tell it as a story a cold reader could follow start to finish.
What we shipped
Concrete, verifiable results: commits (hash plus one-line summary, from the real git log), anything deployed (with the live URL), files created or changed. This is the "it is actually done" list.
What we failed or got stuck on
An honest account of dead ends, rejected approaches, bugs not yet fixed, things that did not work. This is often the most useful section for the next session, because it stops them repeating a mistake that already cost time once.
What we can learn
The lessons and gotchas worth carrying forward: "do not do X again", "Y only works if Z", a surprising constraint discovered this session. Durable, cross-session insight.
Where things stand now
The current state: git (head, branch, pushed or dirty), what is DECIDED and locked versus what is STILL OPEN and waiting on a decision.
Next session - start here
Explicit first steps for the next chat, so it can act immediately instead of spending time orienting.
The file is always ignored
HANDOFF.md is transient session state, not documentation. Add it to .gitignore and keep it there. It should never enter git history - it is rewritten every session and would only churn the log. If .gitignore does not already list it, add it before writing.
Keep the layers clean - handoff is transient, memory is durable
The handoff is what happened this session. It is not where permanent truths live.
If a fact is durable - a hard rule, a standing preference, a constraint that will still be true three sessions from now - it belongs in your MEMORY.md, not buried in a handoff that gets rewritten and pruned. When you notice one, promote it to memory instead of parking it here. The two layers are a pair: the handoff is this session, the memory is everything permanent. See the companion memory system: https://github.com/rb17080/claude-memory
When you rewrite the handoff, prune anything from a previous session that is now done and no longer load-bearing. A handoff that only grows becomes noise.
What not to put in it
No secrets, tokens, API keys, passwords, or private URLs - the file lives on disk and can be copied around. No full file dumps: reference paths and line numbers, do not paste whole files. The handoff points at the work; it is not a copy of it.