handing-off-work
Handing Off Work
Overview
A session ends with two things in it. One is recoverable: what the code looks like now, which git will tell anyone who asks. The other is not: why it looks like that, what was tried and rejected, and what the next move was going to be. That second half exists only in the session, and when the session ends it is gone.
A handoff document is the attempt to save it. Most attempts fail the same two ways, and everything in this skill follows from avoiding them.
State comes from the repository. Reasons come from the session. Never swap them.
An agent writing "I updated the auth middleware" from memory is reporting an intention, not a fact — the edit may have been reverted, superseded by a later one, or never applied. Every claim about what the code is gets read out of git. Memory is used only where the repo genuinely cannot answer: why one approach won, what the third attempt broke, what the user actually wanted.
Write for a reader with no memory of the session.
"The refactor we discussed", "that approach", "the file above", a name coined mid-conversation, an appeal to a todo list the next harness cannot see — each of these is a dead reference to whoever reads the document, and a handoff full of them costs more time than it saves. Every noun must resolve from the document plus the repository alone.