Six weeks after you leave, someone reverts the retry back-off you spent a fortnight tuning, because it looked like a mistake. A month later the same person reopens the vendor question you closed after three weeks of analysis, because nothing said it had been closed. Your handoff doc was long and every fact in it was true.
It answered where. It never answered why.
State is discoverable. Reasons are not
Anything the next owner can find by looking, they will find. The folder layout, the deploy steps, the open tickets, which dashboard shows what — slower than you would like, but recoverable without you.
The constraint that made the obvious option wrong is not recoverable. It exists in one place, which is your head, and on your last day it stops existing. That asymmetry should decide how you spend the writing time: the more discoverable something is, the smaller its share of the document.
Most handoff docs invert this exactly, because inventory is easy to write and reasoning is hard.
Write each decision as a decision plus its constraint
Two sentences. What was decided, and what made the alternative worse.
"We bill quarterly rather than monthly. Monthly was better for cash flow, but the purchasing systems at our two largest accounts only raise POs quarterly, and neither was going to change that for us."
The second sentence does a job the first cannot: it tells the successor when the decision is up for review. The day those accounts change their systems, the reasoning expires. Without it they inherit a rule with no expiry condition, which gets treated either as sacred forever or as arbitrary and overturned on a whim — wrong in the same way both times.
Two things belong alongside each entry. What you decided against, named explicitly, because a closed question with no record reads exactly like an open one. And what evidence would reopen it, which is the difference between a decision and a habit. That is the shape a decision record formalises, and it is worth writing even for the choices that felt obvious — obvious-at-the-time is precisely what fails to survive a handover.
The list of things that look wrong on purpose
The highest-value section in any handoff, and almost always absent for a mechanical reason rather than a lazy one: you stopped seeing them. Every item looked strange to you once, you learned why, and it quietly filed itself under normal.
One line each, four parts — the thing, why it looks like a mistake, why it is actually that way, and what breaks if someone tidies it up.
- The nightly report runs at 03:40 rather than on the hour, because the upstream feed lands at 03:30 and an hour-aligned run raced it.
- One customer's invoices are still generated by hand. Their contract predates the current pricing model, and the automated path produces a number they will dispute.
- There are two staging environments and the older one is not dead. It holds the only copy of the legacy data the migration tests read.
The way to find these is not to think hard. Imagine watching someone new work on the thing, and write down every sentence you would blurt out. Anything starting with "careful, don't" is an entry. Watching them for real for an afternoon works better, because the reflex fires on its own.
The alternative is that the next owner discovers each item by breaking it — one incident per line you did not write.
A routing table, not an org chart
Names attached to questions, not to titles. An org chart says who is senior. A routing table says who actually knows.
"Anything about the billing reconciliation goes to Dana in finance, and only Dana, because she built it. Vendor renewals go to Marcus. The reason the ledger closes on the 3rd rather than the 1st is a question for Priya, who is not on this project at all and is the only person who remembers."
Include the people outside your team, the ones with no formal role, and whoever answers in ten minutes what would otherwise cost a day. Where you can say it kindly, note where the intuitive person to ask is not the right one.
Then hand over the permission with the list. A routing table the new owner does not feel entitled to use is just names. Tell those people the handoff is happening and that questions are coming.
Separate the unfinished from the merely ugly
Two different backlogs, routinely merged into one, and merging them makes both useless.
Ugly and working means inconsistent naming, a manual step, code that embarrasses you. The cost is discomfort, not risk. Label it, or a conscientious new owner spends their first month on cosmetics while the real hazards sit untouched.
Unfinished means something presents as done and is not. The retry logic that was never wired to alerting. The migration that ran for every account except the three largest. The feature behind a flag nobody turned on for the customer it was built for. These are dangerous precisely because they look finished — nobody investigates a green check mark.
Say which is which in plain words, and put the unfinished list first. A third category deserves its own heading: known broken, deliberately not fixed, with the reason. That one stops your successor from refiling the bug you already triaged and declined.
The two artifacts a handoff actually needs
A handoff is not one document. It is two kinds of writing doing different jobs, and it fails when they get blended into a single narrative.
The first is the decision record — durable, one entry per choice that would be expensive to relitigate, written to outlive everyone involved. The second is the context brief: a short passage that makes a cold reader competent for one specific question, and then stops. You do not write one for the whole project. You write one per live thread being inherited, because each is indexed to a different question and each becomes disposable once that question is answered.
Your successor is the coldest reader you will ever write for — all of the artifacts, none of the history, which is the same gap that opens whenever context has to move between two working sessions. For threads that reach outside the company, the handoff has to reach the other side too, and handing off an escalation mid-flight has its own failure modes.
If an assistant sat through the work with you, it can draft the state, the sequence, and the options considered. It cannot testify to your reasons, because it never had them. RelayLink labels every assumption in a package as stated by the sender or inferred by the sender's AI, and a handoff drafted from a session will be mostly the second kind. Those labels are a map of where to go back by hand — they mark the gap honestly, they do not close it. Packages carry text fields only, with no attachments, so a handoff briefing points at where the artifacts live rather than shipping them.
Write the looks-wrong-on-purpose list first, before the folder map and before the org chart. It takes an afternoon, and it is the section your successor will still be grateful for a year later. If you want the first draft pulled from the sessions where the decisions actually got made, connect your assistant.