Short answer
#The folder on the last day
The last day of the old team goes well. There is a final call, everybody is polite, and a folder is shared: credentials, a link to the repository, a document called something like architecture overview, a recording of a walkthrough. The new team says thank you and that it all looks very thorough. The contract is closed.
Six weeks later the new team needs to change how refunds are issued. Nobody can find where refunds are calculated, the overview does not mention them, the recording skipped that part, and the old team now answers emails in a few days, politely, as a favour. The change that was estimated at a week takes four, and most of the extra time is spent finding out things that somebody knew perfectly well on the last day.
Nothing in the handover was dishonest. It was accepted against the wrong thing.
What this article is about
Not about what a handover package should contain, which the handover checklist covers. About how to tell whether a handover worked before the people who could fix it have gone.
#Delivery is the wrong test
Handovers are accepted on delivery because delivery is easy to check. Either the credentials work or they do not. Either the document exists or it does not. The trouble is that every one of those checks can pass while the thing a handover is for has not happened at all.
A handover exists so that the new team can make decisions about the system without the old one. That is a statement about questions and answers, not about files. A document can be long, accurate and useless if it does not answer the questions that come up. A short list of answers with sources can be worth more than everything in the folder.
-
What delivery proves
That the new team can log in, see the code and read whatever was written. Necessary, and quick to verify.
It is a statement about access.
-
What delivery does not prove
That the new team can say where personal data goes, what runs at night, what breaks if a provider changes, or why a strange part of the system is the way it is.
These are the questions that decide how much the next six months cost.
-
What a question test proves
Which of those questions the new team can already answer from the materials, which they can answer only from what somebody said on a call, and which they cannot answer at all.
It is a statement about understanding, and it can be measured.
#Write the questions first
The test starts weeks before the last day, with a list of questions written by the owner and the incoming team together. Not general questions about the architecture, but the specific ones the business will need answered in the next six months.
Good questions come from decisions, and they usually fall into a few areas.
- Data. Where personal data is stored and copied, including backups, logs and outside services. What would have to happen to delete one customer completely.
- Money. Where payments, refunds and invoices are calculated. What happens when a payment provider sends an event twice, or not at all.
- Time. What runs on a schedule, and how anybody would know that it stopped.
- Outside dependencies. Which external services the system calls, which call it, and what happens when each is unavailable.
- Change. How a change reaches production, who can do it, and how it is undone.
- Oddities. The parts of the system that look wrong and are deliberate. Every system has some, and they are exactly what gets broken first by a new team trying to tidy up.
Twenty to forty questions is plenty. Write them down before anybody prepares handover materials, so the materials are written to answer them rather than the questions being chosen to match the materials.
#Run the test while the old team is still there
The test itself is simple and slightly uncomfortable, which is why it is so rarely done. The incoming team answers every question using only the handed-over materials and the system itself, without asking the old team. Each answer goes into one of three piles.
The handover is not accepted when the third pile is empty. It is accepted when the second and third piles have each been resolved into a source or a named unknown.
| Pile | What it means | What to do |
|---|---|---|
| Answered with a source | The new team can answer and can point at what supports the answer: a part of the system, a configuration, a record. | Nothing. This is what a finished handover looks like. |
| Answered from memory | The answer comes from something said on a call or in a walkthrough, and nothing written supports it. | Find the source, or ask the old team to write it down. An answer remembered is an answer that leaves with the next person. |
| Not answered | Nobody on the new team can answer from what was handed over. | Take it to the old team while they are still paid to answer. |
An incoming team answers thirty questions about a booking product a week before the old agency leaves. Eleven are answered with a source. Nine are answered from memory of the walkthrough, and when checked, two of those turn out to be wrong. Ten are not answered at all, most of them about what happens when a payment fails. The folder was thorough. It simply did not cover the part of the system the next quarter of work was about, and now there is a week left to fix that instead of none.
#What the overlap is for
Most handover contracts include a period when both teams are paid. It is usually spent on walkthroughs: the old team presents, the new team listens. Walkthroughs feel productive and leave very little behind, because what is said in them goes straight into the second pile.
A better use of the overlap is to work through the second and third piles, one question at a time. For each, the old team either points at where the answer lives or writes it down where the new team will find it. The aim is not to empty the third pile completely. It is to make sure every question has been looked at by somebody who knows, and has an outcome.
- Schedule it by question, not by topic. A meeting about the payments area turns into a presentation. A meeting about questions seven, twelve and nineteen ends when they have answers.
- Write answers where the system is described, not in meeting notes. Notes are read once. A description of the system is read every time somebody needs it.
- Run the test again before the last day. The second run is faster and shows exactly what the overlap achieved.
#What cannot be handed over
Some questions will not be answered by anybody, including the old team. Why a certain decision was made three years ago, by somebody who left before them. What a scheduled job was originally for. Whether a given customer still depends on an old integration.
These are not a failure of the handover. They are a property of the system, and the honest thing to do is to record them as such: a known unknown, with the question, what is known around it, and the name of the person who will find out if it ever matters. A known unknown in writing is cheap. The same gap discovered in the middle of an incident is not.
The distinction that keeps the peace
A gap the old team never had is different from a gap they did not hand over. Treat the first as an accusation and you lose the cooperation you need for the second. Keep them on separate lists.
#The handover after the handover
A handover does not end on the last day of the old team. It ends a few weeks later, when the new team has made its first real changes and either understood the system or quietly started to drift from it.
The first weeks are when misunderstandings are cheapest to catch. A new team tidies up, renames, moves a scheduled job, replaces a library. Each change is reasonable, and some of them break something the old team would have warned about. The way to see this is to compare the system before and after: one picture taken while the old team was still there, another a month after the new one took over.
The comparison tells you what the new team changed, what it learned that was already there, and which earlier statements about the system can no longer be stood behind. The article on why the second analysis is worth more than the first goes through how to read that comparison and turn it into a short meeting.
#Ten acceptance questions
A starting list. Replace any that do not apply and add the ones your next six months will need.
Ask the incoming team, with sources
Count how many are answered with a source. That number, not the size of the folder, is the state of the handover.
- Where is customer personal data stored and copied, including backups and outside services? The first question of every privacy request and every enterprise customer.
- How would one customer be deleted completely? It forces the full list of places data lives.
- Where are payments, refunds and invoices calculated? Money is where a misunderstanding costs the most.
- What runs on a schedule, and who notices when it stops? Scheduled work fails silently and is discovered from outside.
- Which external services does the system call, and which call it? These are the dependencies a change of provider will hit.
- What happens when the payment provider is unavailable for an hour? It tests whether failure behaviour is understood, not only the happy path.
- How does a change reach production, and how is it undone? A team that cannot undo a change will be afraid to make one.
- Who owns each account the product depends on? Access that stayed with the old team is the most expensive surprise.
- Which parts of the system look wrong and are deliberate? These are what a new team breaks first while tidying.
- What is known to be unknown, and who will find out if it matters? A handover with no unknowns listed has not been honest about them.
#What people do instead
Accept the handover when the folder arrives.
Instead Accept it when the questions have been tested against the folder and every gap has an outcome. The folder is an input to the test, not the result of the handover.
Spend the overlap on walkthroughs.
Instead Spend it on the questions that failed the test, one by one, with answers written where the system is described.
Ask the old team to write complete documentation before they leave.
Instead Complete documentation is written in a hurry, by people on their way out, and nobody checks it. Ask them to answer the specific questions that failed instead.
Let the new team start by rewriting the parts they do not understand.
Instead Understanding first, change second. A rewrite of something nobody understood removes the evidence of what it was for.
Treat every unanswered question as something the old team withheld.
Instead Separate what they never knew from what they did not hand over. Only the second is theirs to fix.
#What this does not guarantee
A question test makes a handover measurable. Plainly, what it does not do.
What this does not do
- It does not make the new team competent. It shows what they understand, not how well they will change it.
- It only covers the questions somebody thought to ask. The list is worth revisiting after the first real piece of work.
- It does not replace the old team for questions about intent. Why something was decided lives with people, and some of those people are long gone.
- It does not prevent drift after the handover. Only looking at the system again, a few weeks later, shows that.
- It cannot be done in the last two days. The test needs the overlap to be worth anything, which is why the questions come first.
The point of a handover is that the next decision about your system does not need the people who just left. Whether that is true can be tested, and the test is cheap compared with finding out six weeks later.
If your current team left on Friday, how many of the ten questions above could somebody else answer on Monday, and from what?