When the engineers who know your legacy code retire: capture knowledge first

Find where the knowledge gap actually is#

The knowledge gap in a legacy codebase sits in the modules where one or two people wrote, reviewed and debugged nearly every change, which is what engineers mean by a low bus factor. Code age alone is a poor guide; a very old module that several people understand is safer than a younger one only its author can touch.

Use the history you already have. Commit authorship, code review approvals, on-call pages and the names that appear in Jira comments on hard bugs all point to the same people. Then ask a direct question in each team: which changes would you refuse to ship if this person were unavailable?

• 1Commit and review history by file path, filtered to recent years.
• 2Incident and on-call records showing who resolves which alerts.
• 3Jira or Linear issues reassigned to the same engineer again and again.
• 4Build, release and deployment steps that only one person performs.
• 5Customer-specific behavior, patches or branches that live in one person's memory.

The knowledge capture checklist#

The knowledge capture checklist below lists the artifacts that preserve the most knowledge per hour of a retiring engineer's time. Assign each artifact an owner on the receiving side, because the successor, not the retiree, decides when it is good enough.

Recorded walkthroughs people will actually use#

Recorded walkthroughs are useful when they are short, specific and searchable. Record one module per session, with the successor driving the questions, rather than a long monologue nobody will rewatch.

Store each recording with a transcript next to the code it explains, and index it by module and by the questions answered. A transcript makes the session searchable, and it can be turned into documentation later.

Before sharing recordings beyond the team, review them. Engineers often show terminals, configuration files and production consoles, which can expose credentials and customer data.

Writing decision records after the fact#

Decision records written after the fact capture the reasons behind a legacy design while someone still remembers them. Use a simple format: the context, the decision, the alternatives rejected and the consequences, and mark each record as reconstructed so readers know it was not written at the time.

Source material is usually scattered across old email threads, Confluence pages, ticket comments and commit messages. Ask the retiring engineer to review a draft rather than write from a blank page; reviewing is faster and draws out details people forget they know.

Linking tickets to commits retroactively#

Linking tickets to commits retroactively turns version history into an explanation. When a commit message carries an issue key, an engineer reading a strange line of code can trace it to the customer report, the discussion and the review that produced it.

Older histories rarely have clean links, especially after a migration from Subversion or another system. A script can match issue keys, dates and authors to propose links, and the retiring engineer can confirm the hard cases. Store the mapping alongside the repository so it survives the next migration.

Keep the retiring engineer reachable, and keep ownership clear#

Keeping a retiring engineer reachable through a consulting arrangement often pays for itself the first time a rare failure occurs. Agree the scope, response expectations and how access to systems will work after their employee accounts close.

Ownership needs attention. While the engineer is an employee, code and documentation produced in the job are generally works made for hire, and 17 U.S.C. 201(b) makes the employer the owner absent a signed agreement to the contrary. Once they return as a contractor, that default largely falls away: the Copyright Office's Circular 30 limits commissioned works made for hire to specific statutory categories backed by a written agreement, so the consulting contract should assign anything they produce.

Scan captured material before it spreads. TruffleHog, an open-source secret scanner, states that it scans Git, chats, wikis, logs and filesystems and can check whether a secret is live by attempting to log in, so use that verification feature with care and with approval.

Illustrative: a freight rating engine and two retirements#

Illustrative: a fictional company sells freight rating and billing software to regional trucking carriers. Its rating engine is written in Delphi, built on a preserved Windows machine and understood in depth by two engineers who plan to retire.

The CTO starts with history: commits, reviews and Jira escalations show that both engineers touched almost every change to the tariff rules module. Over several months they record module walkthroughs with a younger engineer asking questions, review reconstructed decision records and confirm a scripted mapping of old tickets to commits. The build machine is captured as a scripted environment and tested from scratch.

After the retirements, the younger engineer implements a carrier's new fuel surcharge rule alone, using a walkthrough transcript and two linked tickets from years earlier. One retiree remains on a consulting agreement with a written IP assignment.

Why captured knowledge is also a record worth keeping#

Captured knowledge is also a business record worth keeping, because linked tickets, code reviews, decision records and walkthrough transcripts describe how experienced engineers reason about real systems. AI developers building coding assistants look for exactly that kind of human-generated, domain-specific engineering history.

If a company later considers licensing such records, SourceX would assess them with the SourceX Enterprise Data Value Framework: walkthrough transcripts and linked tickets score on domain expertise and human-generated signal, while reviewing recordings adds privacy burden and preparation cost that lower net value. Any license would follow the SourceX five-step transaction, Supply to Rights to Preparation to Approval to Delivery, with recordings of employees checked for notice and personal details before the company approves release.