← Back to the blogLegacy

Taking Over an Undocumented Project: A Five-Step Field Guide

You've inherited payroll software nobody can explain and nobody dares touch. Five steps to understand it, tie it to a spec and start changing it again.

September 16, 2026 · 7 min read

You’ve inherited software that runs every month, that people’s salaries depend on, and that nobody can really explain. The documentation is several versions behind. The people who wrote the overtime logic left years ago. Every change request comes with the same sentence in the meeting: “we don’t know what this will break.”

This guide walks through how to take such a project back, using a payroll system as the running example. Payroll is where that fear is most justified. A bug on a product page annoys someone. A bug in overtime pay lands on hundreds of payslips at once, and every one of them has a person attached.

Payroll, the quiet kind of legacy

Payroll systems rarely make headlines inside a company. They just run. Over the years they collect rules. Overtime thresholds, night-shift premiums, exceptions for part-time contracts, a special case added after an audit. Each one made sense at the time. Few were written down anywhere a newcomer would find them.

So the team that maintains the system does the rational thing and changes as little as possible. Requests pile up in the backlog. Estimates swell to cover the unknown. The debt grows quietly, and boards have noticed. A Cognizant study from October 2025, based on 1,000 senior executives at Global 2000 organizations, expects the share of IT budgets spent on modernizing legacy systems to climb from 26% to 43% by 2030.

The tempting shortcut is to point an LLM at the repository and ask it to document everything. You get something like 70 pages of Markdown. Now the payroll system is documented, and it is just as far out of your hands as before. Those pages connect to nothing, nobody can verify them, and they go stale with the next commit.

The method below rests on a different idea. Build knowledge that is structured, checkable and tied to the code, then let the people who own the rules decide what is right.

Step 1. Pick one module, ideally the scary one

Resist the urge to understand everything. Choose one or two modules and go deep. In payroll, the overtime calculation is a natural candidate. It changes whenever a collective agreement or an internal policy changes, it produces the angriest tickets when it’s wrong, and half the system depends on its output.

A narrow scope gives you a result in weeks instead of quarters. It lets the payroll specialists validate something concrete instead of a slide. And it gives you real evidence for deciding whether the approach deserves a wider rollout.

Good signs that a module is the right pilot:

  • it’s on the roadmap for a change soon;
  • incidents keep coming back to it;
  • people lower their voice when they mention it.

Step 2. Recover the spec, starting with the rules

Lyriks reads the module and rebuilds its specification. It covers the whole module: features, user journeys, actions, business rules, screens, objects and attributes, invariants and testable requirements, and also the technical side, its architecture, modules, dependencies, data model, APIs, integrations and technologies.

Start your review with the rules. For overtime, one rule that surfaces might read “hours worked beyond 40 in a week are paid at 1.5 times the base rate.” Others follow. How a week is defined. Whether paid leave counts toward the threshold. What happens when an employee changes contract in the middle of a week. All of it in business language. A payroll manager can read each rule, challenge it and correct it without opening a single file.

This is often the moment the team relaxes a little. Forty rules on a page are far less frightening than four thousand lines of nested conditionals.

Step 3. Follow each rule to its code

The same spec holds the technical elements the rules depend on. For overtime, that means something like overtime.py, the Timesheet API and the pay_lines table.

The links are where the value is. Each rule points to the code that implements it. The 40-hour rule is linked to overtime.py, the Timesheet API and pay_lines. When someone touches overtime.py, you know which rules are in play. When the policy changes, you know where to act. All of this sits in a graph database rather than a folder of documents, and every element traces back to its source.

SPEC · BUSINESS RULEBeyond 40 h a week,paid at 1.5x baseovertime.pyTimesheet APIpay_linesNEXT RULES TO CONFIRMHow a week is definedDoes paid leave count?Contract change mid-weektouch overtime.py and you know which rules are in play
The overtime rule, written in business language and linked to overtime.py, the Timesheet API and the pay_lines table, with the next rules to confirm.

Step 4. Put every source on the same table

Code is never the only witness. There are Jira tickets, Confluence or Notion pages, Figma mockups of the timesheet screens, and the GitHub history. Bring them into a single knowledge base and compare what each one says.

Expect surprises. In an illustrative case, a Jira ticket says overtime starts after 40 hours per week, a Confluence page says after 8 hours per day, and the code actually computes it over a two-week period of 80 hours. Three sources, three answers, and each team has been working from its own version without knowing it. A daily threshold and a two-week one pay very different amounts to someone who works three long days and then two short ones.

Once the inconsistency is flagged, it stops being a vague worry. It becomes a precise question addressed to the right person, with the three sources attached.

This step also tends to change the tone of the project. Until now the team was afraid of the code. Now it has a list of questions, each with an owner, and a list is something you can work through one line at a time.

Step 5. Let the business decide, then change things under watch

The rebuilt spec goes back to the people who own the rules. For overtime that means payroll and HR, perhaps legal as well. They confirm, correct or arbitrate. Suppose they decide the weekly threshold is the correct one. The code, which uses a two-week period, now has a named gap to close.

From here, the module is no longer a black box. It has an approved spec linked to the code, and changes can start again.

When the next change comes in, say a new premium for weekend shifts, its impact is computed before any code is written. You see what it touches, what stays compatible, what conflicts with the existing rules and what needs a decision. The approved spec then goes to your LLM over MCP with its rules and sources. Lyriks checks the generated code rule by rule and flags every addition, omission or regression, and the loop runs until every rule holds.

If the long-term goal is a migration, the same foundation supports a round trip from legacy code to spec, then business revalidation, then new verified code. The Legacy use case page goes into detail, and Refactor and migrate covers the migration side.

JIRAAfter 40 hper weekCONFLUENCEAfter 8 hper dayCODEAfter 80 hover two weeksQUESTION FOR PAYROLL AND HRWhich threshold is right?SUPPOSE THEY PICK WEEKLYThe code gets a named gap to close
Three sources, three overtime thresholds: weekly in Jira, daily in Confluence, two-weekly in the code. The question goes to payroll and HR, and their answer turns into a named gap.

Mistakes that slow a takeover down

A few patterns show up often enough to deserve names.

Starting with the whole system. The scope balloons, nobody can validate anything, and the project stalls before the first useful result. One module done properly beats ten done halfway.

Skipping the business review. A spec that only engineers have read is still a guess. The payroll manager who says “no, that exception was removed two years ago” is worth more than another week of analysis.

Treating the code as the referee. When the code and the documentation disagree, the code tells you what happens today. Whether that is what should happen is a separate question, and it belongs to the people who own the rule.

Fixing silently. When you find a gap like the two-week threshold, write it down and route it to the owner. Patching it quietly recreates exactly the knowledge loss you set out to repair.

Waiting for perfect sources. You will never have a complete, consistent set of tickets and wiki pages. Start with what exists. The inconsistencies are part of what you are looking for.

Thirty days later

After these five steps, the team still doesn’t know the entire payroll system, and it doesn’t need to. It knows the overtime module precisely, with approved rules tied to the code and a short list of gaps everyone agrees on. That’s enough to start changing it again, and enough to estimate honestly what extending the approach to the next module would take.

The next pay run will probably look exactly like the last one. The difference is that, this time, someone can explain why.

If you’d like to see the method run on a module that looks like yours, book a demo.

Go further

Guide · free · 11 pages

The legacy takeover checklist

What to inventory, recover and decide before you change code nobody understands anymore. Checklists you can tick, and a 30/60/90-day plan.

Keep your software in tune

Start with one module. Lyriks recovers its spec, then verifies every change. All it needs is your repository.