Handoff Note
Compresses a long session into the few things the next person — or the next agent — needs in order to keep going.
When to reach for it
At the end of a session that is not finished: end of day, context running out, passing work to a colleague, or stepping away from something you will return to cold.
What changes
- The note opens with the state in three lines — what works, what is broken right now, what has not been started — instead of a story about your afternoon.
- Every half-done thing is named with its path or branch, so nothing important lives only in your head or in terminal scrollback.
- The next step is written as an action someone can take — a command to run, a file to open — not a topic to think about.
- Dead ends are recorded with what actually happened, so nobody pays a second time to discover that the obvious approach fails.
- State that exists outside the repository — a deployed build, rows written, a flag flipped, a service left stopped — is called out rather than assumed away.
Pairs with
- Explain the WhyRecords the reasoning a diff cannot show — what you rejected, and what would make this the wrong choice later.
- Ask One QuestionWhen you are blocked, work out the single question that unblocks the most — and ask that one, well.
- Disagree With the BriefPush back on a requirement that will not survive contact with reality — with a specific failure case and a way forward.
Handoff Note
Compress the session into what the next person needs to act. They do not need the story of how you got here.
1. State where it stands, in three lines
- What works, and is proven to work
- What is broken or half-done at this moment
- What has not been started
Write it as of now, not as of your intentions.
2. Point at every artifact
Anything that exists outside your head gets a name or a path: the branch, files changed but not committed, the scratch script, the log you saved, the query you kept re-running. Commit the work in progress or push the branch, so the note points at something real rather than at a machine only you can reach.
3. Make the next step an action
Not a topic. A command, a file, an edit to try:
- "Run the checkout suite and check whether the session is null on the second call" — actionable
- "Continue with checkout" — not
4. Record the dead ends
Every approach you tried and abandoned, with the reason it failed. This is the most valuable part of the note, because it is the part the next person would otherwise buy twice at full price.
5. Say what you changed outside the repository
Builds deployed, data written, flags flipped, services stopped, credentials rotated, records created somewhere else. None of this shows up in a diff, and it will quietly confuse anyone who assumes the code is the whole picture.
6. List the open questions and who can answer them
One line each, with what you would do if no answer arrives.
7. Keep it to a page, and leave it where the work is
The change description, the branch, or a file beside the code — somewhere the next person is already going to look.
Rules
- Do not narrate the session. State, artifacts, next step, dead ends.
- Do not write "should be easy". Write what is left and let the reader judge; that phrase has cost more evenings than any bug.
- Do not leave the only record in uncommitted files or scrollback.
- Do not omit what you broke or what you are unsure about. The embarrassing detail is the expensive one to rediscover.
- Do not hand off with the environment in a state you have not described.