The risk is not the person leaving, it is what leaves with them
Most legacy systems have one person who knows why things work the way they do. They know why a batch job runs before another one, why a field is overwritten on the last day of the month, and why a strange exception exists for a customer who left years ago. When that person retires, the code stays. The reasons behind the code do not.
If you are the IT manager facing that date, the goal is not to extract everything the expert knows. That is not possible, and trying will burn the months you have. The goal is to capture the knowledge that is hardest to rediscover, in a form your team can still use after the expert is gone.
What to capture first
Start with the knowledge that exists nowhere else. Code can be read by anyone patient enough. Intent cannot. Prioritize in this order:
- Undocumented business rules. Calculations, thresholds, and exceptions that were added in response to a real event and never written down.
- Hidden dependencies. Which jobs, screens, reports, and downstream systems break if a given table or field changes.
- Operational habits. The manual steps, restart procedures, and month-end workarounds that live in the expert's head rather than in any runbook.
- History of past failures. What went wrong before, what was tried, and why the current design exists.
Skip anything the code can answer on its own. Syntax, file layouts, and the structure of a well-written program are better recovered by analysis than by taking up the expert's limited time. For background on that side of the work, see our guide to understanding a codebase you did not write.
Interview the expert with the code open
A plain sit-down interview produces vague answers. People describe what they believe the system does, which is often different from what it does. Put the code on screen and work through it together.
- Walk a real transaction end to end. Pick a common case, such as a payment, a policy change, or an order, and follow it through the programs, screens, and tables while the expert narrates.
- Ask about the exceptions. Questions like “Why is this branch here?” and “What happens if this value is zero?” surface rules that no specification mentions.
- Record everything. Use audio or video and a transcript, so the explanation stays attached to the exact piece of code being discussed.
- Have a second person ask the questions. Someone who will inherit the system asks better naive questions than the expert would ask themselves.
Keep sessions short and focused on one area each. Two hours on a single module beats a full day of unfocused talking.
Keep the result usable afterward
The most common failure is a folder of recordings and a slide deck that nobody opens after the retirement party. Knowledge only survives if it stays connected to the code it describes and is easy to search.
- Tie each note to its source. Record the program name, paragraph, or form for every rule, so a future developer can check it against the code.
- Write rules in plain language. A business analyst should be able to read an entry without knowing COBOL or Oracle Forms.
- Give it an owner. Assign someone on your team to keep the material current as the system changes.
- Test it before the expert leaves. Have a teammate answer a real question using only the captured material. Gaps found while the expert is still reachable are cheap to fix.
Tools can help here. Replai reads COBOL, Oracle Forms, PL/I, and other legacy code and builds a structured map of business rules, workflows, and dependencies, so your team can ask plain-language questions about the system. Used alongside the interviews, the map gives the expert's explanations something to attach to. Our guides on legacy system knowledge transfer and extracting business rules from COBOL code go deeper on each step.
Start now, even if the date is far away
Retirement dates have a way of moving closer. Begin with a short list of the three or four areas where the expert is the only source of truth, schedule one focused session on each, and record them against the code. A modest, well-organized capture done early is worth far more than an ambitious plan started in the final month.
If you want to see how your existing code can be mapped alongside those sessions, you can look at what Replai does for legacy discovery and modernization.
Frequently asked questions
How early should we start capturing knowledge from a retiring expert?
As early as you can. Retirement dates tend to move closer, and focused sessions on a few critical areas are easier to schedule well before the final month than during it.
What should we capture before anything else?
Undocumented business rules, hidden dependencies between jobs and screens, manual operational steps, and the history of past failures. These are the things the code alone cannot tell a future developer.
Why interview the expert with the code open instead of just talking?
People often describe what they believe the system does, which can differ from what it actually does. Walking a real transaction through the code keeps the explanation tied to the exact programs and tables involved.
Can we rely on recordings and documents alone?
Not by themselves. Recordings that are not linked to the code, written in plain language, and owned by someone on your team tend to go unused once the expert has left.
How can Replai help when a legacy expert is retiring?
Replai reads code such as COBOL, Oracle Forms, and PL/I and builds a structured map of business rules, workflows, and dependencies. Your team can then ask plain-language questions about the system and attach the expert's explanations to that map.
How do we know the captured knowledge is good enough?
Ask a teammate to answer a real question using only the captured material while the expert is still reachable. Any gap they hit is a gap to fix before the expert leaves.