The 40-line note that lets a new Claude Code session pick up where the last one stopped

You close a session on a Thursday night with one test still red. On Friday you open a new one and type "continue". It does not know there was a test, or that you already tried the obvious fix, or that one folder must not be touched.

The usual advice is "keep a notes file". That works until the notes file is a wall of text written from memory at 11 pm. What helped us was making the note small, fixed in shape, and checkable.

Six headings, under 40 lines

At the end of a session we write a HANDOFF.md with exactly these headings:

Done: up to five bullets, each one something you can verify ("added parse.py, tests pass").
Not done: what is left, in order.
Decisions: each one with its reason, on one line. The reason is the part people lose first.
Files touched: real paths, taken from git status, not from memory.
First command: the one command the next session should run before anything else.
Do not touch: files or actions that must stay as they are, and why.

If it grows past 40 lines, cut "Done" first. The next session can read the code. It cannot read your head.

Two rules that make it trustworthy

Collect facts with commands. git status --short and git log --oneline -5 tell you what changed. If you write the file list from memory, it will be wrong about one file, and the next session will believe it.

Check the note before you close it. Confirm every path exists, run the "First command" yourself, and write the result on the last line. A handoff that says "tests pass" when they do not is worse than no handoff.

What it looks like

# Handoff 2026-10-29 17:40
Done
- export.py writes CSV; 6 of 7 tests pass
Not done
1. Fix test_unicode_names (fails on "Zoë")
2. Add --out flag to cli.py
Decisions
- Used csv module, not pandas: no new dependency for a 30-line job
Files touched
- export.py (new), tests/test_export.py (new), cli.py (read only)
First command
- pytest tests/test_export.py -x
Do not touch
- legacy/old_export.py: still used by the nightly job
Checked: pytest tests/test_export.py -x -> 1 failed, 6 passed

The next morning the new session reads that, runs the first command, sees the same failure, and starts on the Unicode bug.

As a skill

We turned this into a plain-text skill so we stop retyping the instructions: session-handoff, one SKILL.md you can read in a minute plus a short WHY.md. MIT licence, free to copy into ~/.claude/skills/.

Honest notes

We tested it by hand on our own projects. We have not measured it with other people's workflows, so we cannot promise it will save you time. It does not replace good commit messages or a README.