Undocumented business logic: how to recover the rules your legacy system runs on

Why the rules go missing

Legacy systems accumulate rules over years: a pricing exception for one customer group, a rounding choice finance relies on, a nightly job that fixes records nobody else touches. The people who asked for them move on. The documentation, if there was any, stops being updated. The system keeps running the rules faithfully, and it becomes the only complete record of how the business works.

Why reading the code is not enough

Generating documentation from source code is useful, but it describes what the code could do rather than what the business relies on. It misses several things:

• Code paths that are never used, and rare paths that matter a great deal.
• Behavior driven by configuration and data rather than code.
• Batch jobs, scheduled queries and exports that sit outside the main application.
• Reports and dashboards whose numbers depend on particular data states.
• The reason a rule exists, which only the owners know.

Buyers need coverage: confidence that the important behavior has been found and confirmed. Volume of generated text is not coverage.

A practical method

Observe real behavior

Instrument the running system to record requests, jobs, queries, errors and business outcomes across representative workflows and business cycles, including month-end and other rare events. Redact sensitive payloads. Treat what has not been observed as an explicit gap.

Read code, schema and reports

Use the code, schema, migrations and report definitions to explain what was observed and to find paths that were not. Map report fields back to the data and rules that produce them.

Review with owners, using evidence

Put what you found in front of the people who know the business. Evidence makes the conversation concrete: "on the 14th, 312 invoice lines were created with a zero amount; is that intended?" gets a better answer than "how does invoicing work?".

Write rules as testable requirements

Give each rule a stable ID and write it in a structured, testable form. For example: While an allocation has no rate card, the system shall flag the invoice line as unbillable rather than invoicing at zero. Link each requirement to where it came from and, later, to the work that implements it.

Track coverage and gaps

Agree a confidence threshold with owners and engineers for the workflow in scope: critical rules, data states, exceptions and business cycles. Record what is known, what is uncertain and what has been deliberately excluded.

Keeping it current

Recovered rules are only valuable while they stay true. Link documentation to the work that changes the system, so that when a change reaches done the relevant pages are updated. Then the next change starts from what is known rather than from memory.