← Back to the blogLegacy

Reverse Documentation vs. Reverse Specification: The Difference That Matters

Reverse documentation gives you pages of text. Reverse specification gives you a model of the whole system, linked to the code and checked.

August 18, 2026 · 5 min read

When a team inherits software it no longer understands, the first request is usually “we need documentation.” It is a fair request, and it often gets the wrong answer, which is one of the quieter reasons legacy takeovers stall.

Text about the code, or a model of it

Documentation is text. It comes in many kinds: user guides, code comments and READMEs, technical write-ups of the architecture, functional descriptions of what a feature does. Reverse documentation produces the same thing from existing code, often with an LLM: pages that describe the software.

A specification is something else. It is a model of the software, and it covers all of it: features and user journeys, business rules and invariants, but also architecture, modules, data, APIs, integrations and infrastructure. Reverse specification rebuilds that model from the code, links each element to the lines that implement it, and keeps it checkable.

Confusing the two gets expensive. A team orders documentation, receives tidy pages and diagrams, and finds out weeks later that it still can’t tell whether changing a weight bracket will change what customers pay, or which services that change will touch. The pages describe the system. They don’t let anyone verify it.

Side by side

At Lyriks, we draw the line like this.

Reverse documentation Reverse specification
What you get Pages of text, sometimes with diagrams A structured model: rules, journeys, screens, modules, tables, APIs, infrastructure
What it covers What its author chose to write about The whole system, functional and technical, in one place
Link to the code None, or a file name in a sentence Every element points to the code that implements it
Can you check it? No, you read it and trust it Yes, rule by rule, against the code
Next month Drifts as the code changes Gaps between spec and code are flagged
DOCUMENTATIONText about the codeUser, code, technical orfunctional: all prose.It drifts. Nobody checks it.LYRIKS SPECA structured, linked modelFUNCTIONALBEHAVIORTECHNICALARCHITECTUREDATAINFRAEVERY ELEMENT LINKED TO CODEVerified against the code.
Documentation of any kind is text written about the code; it drifts and nobody checks it. The Lyriks spec is a structured model, functional, behavioral, technical, architecture, data and infra, each element linked to the code and verified.

Shipping fees, read twice

Take a legacy e-commerce backend and its shipping fees.

The documentation reads well. A page explains that parcels are priced by weight and destination, that islands have their own grid, that orders above a set amount ship free, and that a ShippingCalculator service reads a shipping_rates table. Useful for onboarding. But nothing tells you whether the page is still true, and a sentence cannot be tested.

The spec holds the same knowledge as elements you can query and check. Parcels are priced by weight bracket and destination zone. Above a weight threshold, a surcharge applies. Islands have their own grid. Orders above a set amount ship free, to the mainland only. One invariant goes with all of it: the fee shown in the cart is the fee charged at payment. In the same model sit the technical elements, the shipping_rates table, the ShippingCalculator service, the carrier API that confirms the zone at checkout, and the separate endpoint the cart screen calls for its estimate.

Look again at the invariant and those two endpoints. If the cart estimate and checkout use different code paths, the invariant may already be broken. A page of text will not tell you. A spec that holds the rule and both code paths will.

Every element linked to the code

A model is only as good as its links to the code. In Lyriks, every rule points to the code that implements it. The island surcharge links to the branch in ShippingCalculator that applies it, to the rows of shipping_rates it reads, and to the screen where the customer sees the result.

That opens up questions you couldn’t ask before.

  • If I restructure shipping_rates, which business rules move with it?
  • Is the free-shipping threshold implemented once, or in the cart and again at checkout?
  • Which parts of the code carry no known rule at all, and might be dead or misunderstood?

It takes the right structure. A RAG pipeline retrieves passages that look like the question. It cannot guarantee that a rule is tied to a specific file, and it cannot walk the relationships exhaustively. Lyriks runs on a graph database where every rule, screen, module and table is a node, every relationship is explicit, and every element keeps its source.

RULEIsland surchargeCODEShippingCalculatorTABLEshipping_ratesSCREENWhere the fee showsRestructure the table:which rules move?INVARIANTFee shown in the cart = fee charged at paymentCART ESTIMATECHECKOUTTWO CODE PATHS?
The island surcharge rule linked to the ShippingCalculator branch, the shipping_rates rows and the screen; the cart-equals-payment invariant is checked across both code paths.

When the sources disagree

Those links also expose something every team suspects and nobody can measure, namely inconsistencies.

Bring code, Jira, Confluence, Notion, Figma and GitHub into one knowledge base and they start to show. An illustrative case. The Jira ticket that launched free shipping sets the threshold at $50. The help center page on Confluence says $60. The code applies $50 at checkout and $60 in the cart estimate.

Which is right? Not necessarily the code. Code is the source of the implementation, and the real reference is what the business meant to offer. Only the business can decide, and only if the gap reaches them with its sources attached rather than sitting quietly until a customer complains.

Once they decide, the decision sticks. The rule is updated in the spec, the mismatch with the code becomes a precise item to fix, and the next change to ShippingCalculator, whether a person or an AI agent makes it, gets checked against the confirmed rule.

Same question, same answer, next month too

One requirement separates an analysis tool from a text generator. Ask twice which rules touch shipping_rates and you should get the same answer twice. The engine here is built on graph rewriting, developed in-house, and is patent pending. It computes answers from the graph instead of producing plausible ones, which is what lets the spec serve as a reference while the code keeps moving.

The Product page shows what the spec covers. If your team has documentation today, keep it: it is good for onboarding. Then ask which question it can’t answer, such as what a change will break. That is the job of the spec.

Keep your software in tune

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