The code was the easy half
When an outside team finishes, the deliverable everybody inspects is the source. It has a line in the statement of work, it has an acceptance checklist, and it is almost never the thing that fails. Source code is a set of instructions for a computer. It is not an explanation. The eight months of decisions behind it — why that threshold is 0.62 and not 0.7, why the second data feed is authoritative on weekdays and the first one on weekends, why a retry was capped at three — lived in conversations between four people. When the engagement ends, those four people go somewhere else, and the conversations do not transfer with the repository.
What breaks after a handoff is rarely code that will not compile. It is a competent engineer opening a perfectly readable codebase and still being unable to change anything safely, because every change might violate a rule nobody wrote down. That engineer is not slow and not unqualified. They are working without the context that made the system make sense, and reconstructing that context by experiment is slow in a way that surprises everyone who has not watched it happen.
Four things leave with the team, in roughly ascending order of how expensive they are to get back.
The credentials. The cloud account, the DNS registrar, the code-signing certificate, the app-store listing, the monitoring dashboard, the API keys for four third-party services, the alerting phone number. Individually trivial. Collectively they are the reason a handoff stalls in week one, and several of them are frequently registered to a person's work email at a company you no longer pay.
The environment. Not the production servers, which are usually fine. The ability to stand up a working copy of the system from nothing, on a machine that has never seen it. The exact runtime version, the local certificate, the seed data, the environment variable nobody documented because it was set on everyone's laptop in month one.
The reasons. Every non-obvious choice in a codebase is either a mistake or a scar. The problem is that they look identical from the outside. A new team deletes what looks like a pointless retry loop and rediscovers, in production, the flaky upstream API it existed to survive. This is the most expensive loss and the least visible one, because nothing about it is missing — the code is right there.
The relationships. Somebody at the data vendor who answers on the second email. The support engineer at the payment processor who knows your account. The person on your own finance team who explains the reconciliation rule. None of this is in the contract, all of it is load-bearing, and it is the category buyers never think to ask for.
You are probably here because
- An engagement is ending in six weeks and nobody has said the word handoff out loud
- The one person who understands the system has given notice
- You own the code, you have read the code, and your team still cannot deploy it
- You are about to sign with a firm and want the exit written before the entry
The clean-machine test below tells you in half a day whether the handoff is real. The clauses section is what you write before signing. If it has already happened, skip to the recovery order near the end.
The test that tells you whether a handoff is real
There is one test, it costs half a day, and it settles the question that a hundred pages of documentation cannot. Take someone who has never touched the system. Put them on a machine with nothing installed. Give them the runbook and nothing else — no Slack, no phone call, no reading over a shoulder. Ask them to stand the system up locally, run the tests, and deploy a one-character change to a staging environment.
Every question they have to ask is a defect in the document. Log each one. Most teams fail inside the first hour, and they fail on credentials rather than on anything intellectually interesting. That is good news: credential problems are cheap to fix while the vendor is still being paid, and nearly impossible to fix three months after the final invoice.
Run this test at the midpoint of the engagement, not at the end. At the midpoint it produces a task list. At the end it produces an argument.
| What to require | Cost during the engagement | Cost to reconstruct afterward |
|---|---|---|
| Clean-machine setup a stranger can follow | 1–3 days, written once and corrected as it drifts | 1–4 weeks of trial and error by someone who was not there |
| Every account owned by your organization | A few hours in week one | Weeks, and it depends on cooperation you no longer command |
| A decision log: why, not what | About an hour a week | Largely unrecoverable. You re-derive it by breaking things |
| Tests that fail when the system is actually broken | Part of the build, if asked for at the start | Months, or you accept that nobody changes the system |
| Data lineage for every field that matters | Days, while the pipeline is being written | Months of reverse engineering against live data |
| A second person who has done the work | A modest overlap in hours | A hiring cycle plus a ramp, with the system frozen |
Account ownership is the failure that shows up first
On day one of an engagement, it is faster for the vendor to create the cloud project, register the domain, and sign up for the third-party APIs under their own organization. Genuinely faster — sometimes by a week, because your procurement process exists and theirs does not. That speed is borrowed, and the interest is paid at the end.
The rule that avoids all of it: you create every account, the vendor gets access to it. Cloud accounts in your organization with the vendor as a role. Domains at your registrar. Third-party API keys in your name, billed to your card, shared through your secret manager. Repositories in your GitHub or GitLab organization from the first commit. Code-signing certificates and app-store listings under the company that will still exist in five years.
This adds real friction in week one and removes an entire failure category forever. When it is skipped, the recovery is not an engineering problem. It is a support ticket with a company that has no commercial reason to prioritize you, sometimes about an account owned by an employee who has since left them too.
How much of a system survives a cold handoff — by artifact
Our judgment from projects we have inherited, not a measurement. The ordering is the useful part, and it is stable across every one of them.
Write the exit into the entry
Every clause below is easy to agree to before work starts and nearly impossible to add afterward, because after the work starts you are asking for a change and the answer is a change order. None of them are unusual, and a firm that resists all six is telling you something worth hearing.
Documentation is a deliverable with acceptance criteria, delivered continuously. Not a final report. A final report is written by a person who has already mentally left, and it describes the system they wish they had built. Tie a small share of each milestone payment to documentation that passes the clean-machine test at that milestone.
All source in your repository from the first commit. Not delivered as an archive at the end. The difference matters: a live repository carries the commit history, and the commit history is the only honest record of what was tried and abandoned.
Every account under your organization, no personal email addresses on anything. Audit this in month one rather than believing it.
Two people touch the system, even if one of them is at twenty percent. A single named engineer is the cheapest bid and the most expensive risk. The second person does not need to be full time. They need to have deployed it, debugged it once, and be reachable.
A termination assistance period, priced before anyone is unhappy. Thirty to ninety days after the engagement ends, at an agreed hourly rate, covering questions, one incident, and knowledge transfer. Negotiating this while the relationship is good costs a paragraph. Negotiating it during a dispute costs whatever they ask.
Final acceptance is conditioned on the rebuild, not on a demo. The demo proves the system works on their machine. You already knew that.
Doing this well is a small line item. Recovering from not doing it is not.
Continuous documentation, account hygiene and a second engineer typically add somewhere in the range of three to eight percent to an engagement — and some of that comes back as fewer questions later. Recovery after a cold departure runs very differently: for a system of moderate size we would budget four to twelve weeks of a senior engineer doing archaeology before the first feature ships, plus a feature freeze while it happens. At commercial senior engineering rates that is a five-figure sum at the low end and well into six figures for anything substantial. The freeze is usually the part that hurts.
The overlap is the only thing that reliably transfers judgment
Documents transfer facts. Overlap transfers judgment, and judgment is what you are actually short of. The mechanism that works is reversed pairing: the incoming person does the work while the outgoing person watches and corrects. Not a walkthrough, not a recorded demo, not a wiki page. The successor's hands on the keyboard, the incumbent's mouth doing the talking.
Two to four weeks is the range we would ask for on a system that took two people six months to build. In the first week the successor drives every deployment. In the second they take a real support ticket end to end. Somewhere in there they should break something in staging and fix it, because recovering from a mistake teaches more about a system than any successful change.
This is the line item that gets cut when the project is late, and the project is nearly always late. It is worth protecting precisely then. A schedule that is two weeks over is a two-week problem. A handoff that did not happen is a two-quarter problem that arrives after everyone has stopped paying attention.
When the vendor is already gone
If you are reading this after the fact, the order of operations matters more than the effort. Teams that inherit a system and start by trying to understand it usually spend a month and understand it slightly. Teams that follow this order get control in about a week.
First, take ownership of everything. Inventory every account, credential, domain, certificate and third-party service. Move what you can into your organization. Rotate every secret. Find out which of them auto-renew and on whose card. Do this before anything technical, because it is the part with an external dependency and external dependencies have lead time.
Second, prove you can deploy. Before understanding anything, ship a one-character change all the way to production. Change a label. If you cannot do that, nothing else you learn is actionable, and this single exercise finds most of what is broken.
Third, draw the map before fixing anything. Components, data flows, external dependencies, everything that runs on a schedule. Scheduled jobs are the classic ambush: a nightly process nobody mentioned, that nothing monitors, that half the reporting depends on.
Fourth, write characterization tests. Not tests of what the system should do — tests of what it currently does, on real inputs, including the behavior that looks wrong. Some of that behavior is a requirement somebody forgot to write down, and you will find out which by changing it in front of a customer.
Only then start changing things. And resist the rewrite. A rewrite of a system nobody understands reproduces the bugs while losing the undocumented requirements, and the undocumented requirements are the reason the system is more complicated than it looks. Rewrites of inherited systems are the most reliably underestimated work in this industry.
A thirty-day handoff that actually works
The last two days are the ones that get waived, and they are the only ones that prove anything. Being unreachable for forty-eight hours by prior agreement is a kinder test than the unplanned version, which is the one most companies get.
The mistakes we are called in to fix
- The handoff is a meeting, scheduled for the last afternoon of the engagement
- Documentation was a final deliverable, so it describes an idealized system nobody built
- Accounts live in the vendor's organization, including the domain and the signing certificate
- One engineer knew everything, and the bid was cheaper for exactly that reason
- No termination assistance clause, so post-engagement questions are billed at whatever is asked, if answered
- Acceptance was a demo, run by the person who built it, on the laptop where it works
- Scheduled jobs nobody inherited, discovered when a monthly report silently stops
- The successor was hired after the incumbent left, so the overlap was zero by construction
Before the last invoice is paid
- A person who never touched the system rebuilt it from the runbook alone
- Every account, domain, certificate and API key is owned by your organization
- Every secret has been rotated and the vendor's access has been revoked and verified
- Two of your people have deployed to production without help
- Every scheduled job is documented, monitored and attributed to an owner
- The decision log exists and explains the ten choices that look wrong
- Data lineage is written down for every field that appears in a report someone reads
- A termination assistance period is in the contract at a stated rate
- Third-party contacts are named, with account numbers and support tiers
- Someone on your side has recovered from a failure, not just watched one being explained
Bottom line
A handoff fails for one reason: the valuable part of an engagement was never written down, because writing it down is nobody's favorite work and no milestone depended on it. The fix is not a bigger document at the end. It is a small amount of structure at the start — your accounts, your repository, two people instead of one, and a rehearsal in the middle of the project rather than a ceremony at the end. That structure costs a few percent. Skipping it costs a quarter of engineering time and arrives when nobody is watching for it. If you are signing anything this month, the six clauses above are the whole article.
Frequently asked questions
Roughly thirty days of calendar time for a system two people built over six months, with the successor doing real work for most of it. What matters is not the duration but the structure: a clean-machine rebuild, reversed pairing where the incoming person types, and a period at the end where the outgoing person is unreachable by agreement. A handoff measured in meetings rather than in work performed has not tested anything.
A setup procedure that works on a clean machine, an inventory of every account and credential with ownership confirmed, an architecture map including scheduled jobs, data lineage for the fields that appear in reports, a decision log explaining the choices that look wrong, third-party contacts with account numbers, and a runbook for the three failures that have actually happened. Code and infrastructure definitions are assumed, not the package.
Budget four to twelve weeks of a senior engineer before the first new feature ships, and expect a feature freeze for part of it. The range depends far more on account access and test coverage than on how much code there is. If credentials are clean and tests exist, the low end is realistic. If the domain is registered to a former employee of a former vendor, add weeks that have nothing to do with engineering.
Almost never as the first move. A rewrite reproduces the bugs you know about and discards the undocumented requirements you do not, and those requirements are the reason the original looks over-complicated. Learn it, write characterization tests around what it actually does, then replace it in pieces if replacement is still warranted. The decision looks different after four weeks than it does on day one.
Documentation as a milestone deliverable with acceptance criteria; source in your repository from the first commit; all accounts under your organization; a second named engineer with real hours on the system; a termination assistance period of thirty to ninety days at a stated rate; and final acceptance conditioned on an unassisted rebuild rather than a demonstration. All six are easy to agree to before work starts and expensive to add later.