What happens when the only engineer who understands a system leaves

A payments service has run for six years. One engineer wrote most of it, reviewed most of the changes to it, and answered every question about it in chat. They hand in notice. The handover plan is a two-week knowledge-transfer document and a recorded walkthrough.

Nothing breaks on their last day. That is what makes the problem hard to see. The service runs, the dashboards are green, and the loss shows up months later, the first time someone has to change a rule and nobody can say why it is the way it is.

How common is a system only one person understands?

More common than most teams assume. A study of 133 popular GitHub projects estimated each project’s “truck factor”: the smallest number of developers who would have to leave before the project lost most of its knowledgeable authors. For 65% of the projects it was two or less¹. Those are open-source projects, and the method estimates knowledge from who wrote which files, so treat the numbers as an indication, not a measurement of your company.

Still, the shape will be familiar. Knowledge concentrates in whoever wrote the code first and kept maintaining it, because that is the easiest way for work to get done. Nobody decides to make one person a single point of failure. It happens one convenient question at a time.

Tenure makes this a matter of when, not whether. The median US worker has been with their current employer for 3.9 years². A system that outlives its authors by a decade will be maintained mostly by people who never met them.

What actually leaves with the engineer?

Engineers who have been through this describe the same thing⁴. Comments say what the code does. The architecture decisions, the options that were rejected and the incident that explains a strange limit live in one head. One account of a departing senior engineer puts it plainly: the code was not the loss, the context was³.

Break that context into pieces and each has a different fate:

• What the system does. Recoverable. The code is still there, and a patient reader can work it out.
• Why a rule has its current value. Mostly gone. The 30-day window, the manual review above a threshold, the region that skips a check. The code shows the number, not the decision.
• What was tried and rejected. Gone. Nobody records the design that did not ship.
• Who else cares. Often gone. The engineer knew that Finance relied on a field and Support relied on a status. That map existed only in their experience.
• How sure anyone is. Gone. The engineer knew which parts they understood well and which they had guessed at.

The first item is why a departure feels survivable. The rest are why it is not.

Why doesn’t a handover document fix it?

A handover document is written by the person with the most context, at the moment they have the least time and the least motivation. It lists services, repositories, runbooks and on-call notes. It tends to answer the questions the departing engineer expects to be asked.

The questions that matter are the ones nobody expects. Nobody knows to ask about the refund exception until a customer hits it. The engineer who could answer in thirty seconds is now at a new company, and the document says nothing.

Time is the other problem. Years of accumulated context cannot be transferred in a two-week notice period, and a recorded walkthrough captures what the engineer thinks to say, in the order they think of it. It is also a one-way broadcast. Nobody on the receiving end knows yet what they will need.

Exit interviews built for knowledge capture help, and the advice in knowledge-management guides is sound: start early, capture the “how and why” and not only the “what”, and overlap the leaver with a successor where possible⁵. The weak point is the same. It depends on the right questions being asked before the person is gone.

What does it cost when nobody can say why?

Usually it shows up as one of three failures.

A change made without the reason. Someone changes a limit because the business asked, and the limit was protecting something no one remembers.

A deletion that looked safe. Code with no comment and no test looks like a leftover. Engineers have followed Chesterton’s fence for a century for this reason, and AI coding tools make the deletion faster; see why AI tools get your business rules wrong.

A slow tax on everyone. When the reason cannot be found, the cautious choice is to ask around, and the answers contradict each other. Field studies suggest engineers already spend most of their time understanding existing code. Losing the person who held the answers makes that time longer.

What can a team do before the notice letter arrives?

You do not need new tooling for the first steps.

1. Find your single points of failure. For each important service, ask who could explain its ten most consequential rules. If the answer is one name, that name is your risk, whether or not they are planning to leave.
2. Ask early, in small pieces. A handful of specific questions across several months produces better answers than a two-hour interview in the last week. Specific, contrastive questions work best: “why 30 days rather than 60?” gets a reason, while “please document the refund policy” gets a paragraph nobody reads.
3. Record the reason with its owner and date. An answer in a chat thread disappears. An answer attached to the rule, with who said it and when, can be checked and corrected later.
4. Write down what is still unknown. “Nobody knows why” is useful information. It tells the next engineer to stop and ask instead of assuming.
5. Move ownership explicitly. A rule whose owner has left and who has no replacement is a rule nobody will remember to question.

Where does organizational memory fit?

This is the situation AppThentic was built for. The When someone leaves guide describes the approach in four steps.

First, Coverage lists the rules where the leaving person is the owner or the only person with an answer, so you start from a measured list and not a hunch. The rules are ranked, with those that change often or carry the most money and risk first. Then om, AppThentic’s question-asking model, asks the person a few questions a day across their notice period, rather than one brain dump at the end (see asking the right questions). Finally, each rule moves to a new owner, who sees the approved reason along with the original owner’s name and date.

The answers go into Organization Memory, attributed and dated, and they stay after the person has gone. If a rule they explained changes later, the new owner is asked to confirm that the reason still holds.

Two properties matter for honesty. A person who does not know is recorded as not knowing, and the question moves on to whoever might (finding the owner). And a reason is only shown as approved once its owner has approved it; until then it is marked inferred or unknown. A reason that was guessed is not presented as fact. See rule statuses.

The docs also suggest running this for anyone who has held a role for several years, not only for people who are leaving. The best time to ask is while they still remember, and while the answer is not tied to a deadline.

AppThentic does not make a departure painless. It does not recover reasons the person never knew, and it depends on the person answering. What it changes is when the question gets asked and where the answer ends up.

What to do this week

Pick the one system your team would least like to lose its expert on. List its ten most consequential rules, and next to each write who could explain it today and where the reason is recorded. Anything marked “only them” or “I think it was someone who left” is a question to ask now, in small pieces, while the person is still down the hall.

If you want to see this applied to your own systems, book a walkthrough.

Sources