Handoff Notes: How Work Survives a Change of Hands
Software work rarely happens in one sitting by one person. A feature is started on Monday and finished on Thursday. A bug is investigated by one person and fixed by another. An AI working session ends, and a new one picks up later with no memory of what came before. Every one of those transitions is a chance for important details to be lost.
Handoff notes are our answer. Each significant piece of work keeps a living document that tells the next person exactly where things stand. Here is what goes into one and why.
What a handoff note contains
Our handoff notes follow a consistent shape, so readers know where to look:
- What was asked. The original request in plain words, including who asked and any limits they set.
- What was built. The changes made, with the files and areas involved.
- What was verified, and how. Each check that was run, with its result.
- What remains. Open tasks, known gaps and anything deliberately left for later, with the reason.
- What must not be done. Holds, approvals still needed and actions that are not authorized.
- Where the evidence lives. Screenshots, logs or records that support the claims above.
The fifth section is easy to forget and often the most important. A future reader needs to know not only what to do next but what they must not do without permission.
Evidence comes in separate columns
One habit makes our handoffs especially useful: we keep different kinds of evidence separate. That code was written and reviewed is one fact. That it passed automated checks is another. That it was released to production is another. That a real person used it successfully in a browser is another. That a payment provider accepted a real transaction is yet another.
Mixing those together produces statements like "done and working" that mean very little. Separating them lets the next reader see exactly what has been proven and what has not.
Dates and identifiers, not vague references
"Recently fixed" means nothing a month later. Handoff notes use real dates, release identifiers and specific record numbers where relevant. "Released on October 11 in the build that added the blog library" is something a reader can check. "Fixed last week" is not.
Honest about failures and skips
If a check failed, the handoff says so and shows the result. If a step was skipped, the handoff says it was skipped and why. If something could not be verified because a service was unavailable, that is written down too. A handoff that only records successes encourages the next person to trust work that has not earned it.
Handoffs connect to the evidence, not just describe it
A handoff that says "tested on phones" is less useful than one that points to the screenshots. Where possible, our notes link to the evidence directly: the release identifier, the saved screenshots, the record numbers that were checked. A future reader can then confirm a claim in seconds instead of repeating the work. This is especially important for anything involving money or customer data, where we keep payment and financial evidence separate from code evidence.
Where handoffs live
Handoff notes live in our documentation alongside the code, in a folder for active work. When a piece of work is finished and accepted, its handoff moves to an archive, where it remains as history. Active notes stay current; archived notes stay accurate for the moment they describe. You can read about that structure in writing documentation that lives next to the code.
Handoffs for AI sessions
AI working sessions make handoffs even more important, because a new session starts with no memory of the previous one. Our project instructions direct every session to read the current handoff before starting related work, and to update it before finishing. The handoff is how a session several days later knows that a decision was already made, a check already passed or an action is on hold.
A short exercise for any team
If you lead a team, try this: pick a piece of work that changed hands recently and ask the person who picked it up what they had to figure out on their own. Each answer is a line that belonged in the handoff. Over a few rounds, your handoffs will start answering the right questions.
Frequently asked questions
What should a handoff document include?
It should cover what was asked, what was built, what was verified and how, what remains, what is not authorized yet and where the evidence is.
Why separate different kinds of evidence?
Because "the code builds," "it was released" and "a real user completed the task" are different facts. Separating them shows exactly what has been proven.
How do AI sessions use handoff notes?
Each new session reads the current handoff before related work and updates it before finishing, so decisions and holds carry forward.
Related Posts
Turning Fixed Bugs Into Regression Checks
The best time to stop a bug from coming back is right after you fix it. Here is how we turn fixes into checks and what we learn from each one.
Writing Code the Next Person Can Understand
Code is read far more often than it is written. Here are the habits we use to keep it clear for the next developer or AI assistant who has to change it.
Why Every Change We Ship Goes Through One Pipeline
We never deploy by logging into a server and running commands. Every change travels through the same automated pipeline. Here is why that discipline matters.
Why Customers Never See Our Internal Phase Numbers
Engineering teams use labels like waves, phases and sprints. Customers should never have to decode them. Here is how we keep internal language out of the product.
Writing Documentation That Lives Next to the Code
Documentation that lives far from the code goes stale quickly. Here is how we organize docs inside each project so they stay current, findable and useful.
Comments (0)
No comments yet. Be the first to share your thoughts!