Inheriting a System: The First 90 Days

From the field: a four-line README and a three-week window

My first instinct was to read the code. For two days I walked through the services, noted class names, and tried to reconstruct the data model. By the end of day three I had a lot of notes and still could not ship a one-line change.

On day three I realised the real mistake: I was learning the wrong thing. The code is not going anywhere; I can read it whenever I want. What was about to disappear was not the knowledge in the code, it was the knowledge in the person — and it had a three-week window.

After that I reversed the order: first how the system runs, then what it does. I spent the rest of those three weeks not reading code, but sitting next to that person and asking questions.

Week one: a single goal

Week one has one goal, and it is not understanding the code: be able to make a harmless change end to end on your own. Add a log line, open the PR, get it reviewed, ship it, then roll it back.

It sounds trivial, but that one exercise teaches all of this at once:

change the code  -> repo layout, which service lives where, how it builds
open a PR        -> who reviews, is ownership defined, what runs in CI
ship it          -> pipeline steps, is there an approval, how long it takes
verify in prod   -> where logs go, where the dashboard is
roll it back     -> is there a rollback path, how many seconds
                    (if there is none, that is your first finding:
                     a system that cannot be undone)

None of this is learned by reading code. And all of it is what you will need the first time something actually breaks. How many seconds a rollback takes is exactly the measure I described in the release management post — in an inherited system, it is what you learn in week one.

The one document you write

At the end of the week, write one thing: “How do we ship from here?” Step by step, as if explaining to someone who knows nothing.

The new person has to write it, because everyone else on the team knows the path and cannot write it precisely because they know it; they cannot see which step needs explaining. You are the only one who cannot see it — which makes you the best author, and that advantage disappears in three weeks.

The same logic applies to runbooks: it is the reason for the shadow week I described in the on-call post. The best person to update a document is the one reading it for the first time.

Weeks two to four: build the map

If you ask for an architecture diagram, someone will give you one, and it will probably describe how things were two years ago. I build the real map from three sources:

# 1) Most-changed files = the hot spots of the system
git log --since="1 year ago" --name-only --pretty=format: \
  | sort | uniq -c | sort -rn | head -30

# 2) Services producing the most alerts = the fragile points
#    (last 3 months of alert history, grouped by service)

# 3) Screens with the most support tickets = the user's pain

Where those three overlap is the real centre of the system — and it is usually a box sitting at the edge of the architecture diagram. There is also a fourth source: the file that changes least but everything depends on. Nobody touches it because everyone is afraid of it, and that is where the most expensive work will come from later.

The questions I try to answer in these weeks: who owns which data? Which external services are we tied to, and what happens when one goes down? What runs at night? What is quietly working that nobody is watching?

The 90-day do-not-touch rule

The biggest temptation for a new joiner is to clean things up. The code is ugly, the names are inconsistent, the same job is done in three places. Your hands itch.

The rule: do not remove a fence before you know why it is there. Most strange-looking code is the trace of a night somebody had. That if block may exist because of one customer’s broken data; that pointless-looking sleep may be covering a race condition.

Adding tests is especially valuable. Capturing the behaviour of a module you do not understand is both the fastest way to learn it and the only safety net you will have when you eventually want to change it.

Five questions for the person leaving

Handover meetings usually consist of screen sharing and walking through code, and they miss the most valuable thing: that person’s instinct. Five questions are enough:

1. What woke you up most often at night? This is where the system is really fragile.
2. Which part are you afraid to touch, and why? The reason for the fear is usually written nowhere.
3. What have you never written down that I need to know? Open-ended, and the one that produces the most.
4. Where do you think the next big problem will come from? Most people are surprisingly accurate about this.
5. If you were me, what would you fix first? And there is usually a reason it was never fixed — ask about that too.

Write the answers down and link them to your decision records. A sentence like “we do not touch this part because...” disappears again at the next handover unless it is on paper.

What to track

What did not work for me

• Reading the code end to end. I spent my first two days on it. Reading code without context teaches nothing; when I read the same code later while chasing a bug, I understood it in half an hour.
• Writing a big “current state analysis” report. I wrote thirty pages, three people read it, and no action came out. What worked was turning each finding into a small backlog item — a separate list of findings dies, the same lesson I paid for in the postmortem post.
• Promising a big improvement in month one. I said “we will rewrite that module in three months”. By month three I had only just understood why it was the way it was, and the plan changed completely. Finish the map before you promise anything.

Checklist

Conclusion

If I had spent those three weeks reading code, there would still be things I do not know today — because that knowledge was never written into the code. Instead I asked questions, sat next to the person, and wrote while they talked. On their last day I had four pages of notes, and I went back to them at least ten times over the following six months.

Inheriting a system is not about understanding it. It is about becoming able to change it safely. Those are different things, and the second one is learned much faster.

The day-90 test: if something urgent broke today, how far could you get without calling anyone? If the answer is “most of the way”, the handover is done. If it is “I would have to call someone”, keep asking while that person is still there.