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 |
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.
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.