handoff

name	handoff
description	Write an end-of-session handoff note — what changed, what's half-done, what's risky, exact next steps — for a teammate or future self. Use at the end of a work session, before a vacation, or when transferring work-in-progress to someone else.

Handoff

Whoever picks this up next — a teammate tomorrow, the user in three weeks — arrives with zero short-term memory of today. Your job is to write the note that makes their first thirty minutes cost five. Write for a competent stranger: no "as discussed," no "the usual place," no pronouns pointing at things only today's session can see.

Gather evidence first

Don't write from memory — write from the actual state: git status and the full working diff, recent commits since the last pushed/shared point, stashes (people forget stashes exist — surface them), test-suite status run now (not recalled), TODO markers added today, and anything relevant from the working session (decisions made, approaches rejected and why).

The note

Write HANDOFF.md (or print, if the user prefers):

1. TL;DR — three sentences max: what this work is, where it stands, what happens next.

2. What changed and why — grouped by intent, not by file ("reworked session expiry to fix the logout bug" — then the files under it, as path:line references). Include the why for anything a reader would question; the why is precisely what evaporates overnight.

3. Half-done — the most valuable section; be brutally honest. For each incomplete piece: exact current state, what remains, and the gotcha that isn't written down anywhere else — the insight currently living only in working memory ("the migration is written but not run", "renamed in the callers but not the tests", "this approach works but I was about to abandon it because…").

4. Landmines — things that look done but aren't; temporary hacks that must not ship (with locations); anything that will bite the next person if touched naively ("the seed data is hand-edited, regenerating overwrites it").

5. Next steps — an ordered list where each item is executable without archaeology: the exact command, the exact file and function, the specific decision to make with the options laid out. "Continue the refactor" is banned; "extract the retry logic in sync.js:140-180 into lib/retry.js, then update the three callers listed below" is the standard.

6. How to verify where things stand — the commands that prove the current state (build passes? which tests are red right now and which reds are expected?), so the next person can distinguish inherited breakage from breakage they caused.

7. Rejected paths — approaches tried and abandoned this session, one line each with the reason. This is the section that saves the next person from re-losing the same afternoon.

Rules

• Never claim work is done that wasn't verified this session — a handoff that oversells state is worse than none.
• If tests are failing, the note says so with the failure names. Honesty over tidiness.
• Length follows entropy: a clean stopping point earns a short note; a messy mid-refactor state earns a long one. Never pad, never truncate the mess.