handoff-writer

Handoff Writer

Write a handoff document summarising the current conversation so that a fresh agent — with no memory of any of it — can continue the work.

Derived from handoff by Matt Pocock (mattpocock/skills, MIT), which saves to the operating system's temporary directory. This version asks where to save instead, because the right place depends on how long the handoff needs to live and who else should see it. The rest of the instruction is his.

ASK BEFORE WRITING

Do not write the file until the destination is settled. Offer these, with the trade-off stated, and recommend the one that fits what the person just told you they are doing:

Where	Good for	Cost
Repository root, untracked	Work resuming in this repo, possibly after a branch switch — an untracked file survives checkout	Shows up in git status and can be committed by accident
The OS temp directory	A handoff nobody else needs and nothing should outlive	Easy to lose; some systems clear it on reboot
A path they name	Anything else — a docs folder, a shared drive, a scratchpad	Theirs to manage

If they choose the repository root, offer to add the file to .git/info/exclude. That keeps git status clean without touching .gitignore, which would carry the entry to the remote and to everyone else. Use the common git directory, so the exclusion also applies in worktrees:

git rev-parse --git-common-dir

Append the file name there only if they say yes. It is per-clone and reversible; say so.

WHAT TO WRITE

Do not duplicate content already captured in other artifacts — specs, plans, ADRs, issues, commits, diffs. Reference them by path or URL instead. A handoff that restates a committed document goes stale the moment that document changes, and the reader cannot tell which copy is true.

Write down what exists nowhere else: the decisions taken and why, what was tried and abandoned, the state of anything half-finished, and the traps discovered along the way.