Reverse Specification: Recovering What Your Code Is Supposed to Do
Reverse specification pulls business rules, journeys and invariants out of existing code, each linked to its source. A walkthrough on a streaming platform.
August 12, 2026 · 5 min read
Your software works, and nobody can quite explain why it behaves the way it does. Reverse specification is the work of recovering, from the code itself, what that code is supposed to do.
To keep this concrete, we’ll follow one team through it. Streamly is a fictional streaming platform. Its subscription module is old, has been changed by many hands over the years, and more recently by AI agents too. The team wants to launch a family plan. Nobody is sure what happens today when a subscriber switches plans in the middle of a billing month.
Code that runs, intent that’s gone
Streamly’s situation is ordinary. The original specs describe a version of the product that no longer exists. Tickets describe changes, rarely the state they leave behind. The people who decided how edge cases should behave work elsewhere now. What remains is the code, running in production and trusted by nobody.
The symptoms are easy to spot. Estimating a plan change takes three weeks of digging. Nobody dares delete a condition whose purpose is unclear. New hires need months to become productive. And as AI writes a growing share of the code, the gap widens, because the team produces faster than it understands. None of this is anyone’s fault. It is what happens to software that succeeds and keeps changing for years.
Reverse specification starts from the code because the code is the only reliable record of what the software does today. From there, it extracts the business intent in a form people can read, argue about and verify.
Inside a reverse specification
A reverse specification describes the “what” of your software, independent of how it happens to be written. Lyriks covers features and user journeys, the actions available on each screen, business rules and their conditions, business objects and their attributes, invariants (what must stay true no matter what), and the testable requirements that follow from all of that.
For Streamly’s subscription module, a few entries might read like this.
- Journey. Change plan, from the account page through to confirmation.
- Rule. A downgrade takes effect at the start of the next billing period.
- Rule. An upgrade takes effect immediately, and the price difference is prorated over the days left in the period.
- Object. Subscription, with its plan, start date, billing anchor and status.
- Invariant. An account never has more than one active subscription.
No file names, no class names. Whether proration happens in a stored procedure or in a service class doesn’t change the rule, and that is exactly why a product manager can review it.
The implementation isn’t lost, though. Every element stays linked to its source. The proration rule points to the code that computes it, so anyone who questions the rule can jump straight to the line that enforces it.
Graph, or summary?
It is tempting to point an LLM at the repository and ask what the subscription module does. The result looks like a spec. It rarely behaves like one. Nobody can verify a summary sentence by sentence, it doesn’t update when the code changes, and two runs give two different texts.
Lyriks builds the knowledge base on a graph database, not a RAG pipeline. Every feature, rule, screen and object is a node, connected to the others and to its place in the code. That structure answers precise questions. Which rules touch the Subscription object? Which screens trigger the change-plan action? Which parts of the code aren’t tied to any known rule?
The engine working on the graph is deterministic. It is built on graph rewriting and developed in-house. Ask the same question twice and you get the same answer, which is what makes the spec usable as a reference and not just as reading material.
Streamly’s family plan, worked through
Reverse specifying the subscription module gives the team the change-plan journey, the actions at each step and the rules listed above. It also turns up two surprises.
The first is a duplicated rule. Proration exists twice, once behind the web account page and once behind the mobile app, and the two round differently. A subscriber who upgrades on a phone pays a few cents more than one who upgrades on a laptop. Nobody decided that. It simply happened over the years.
The second concerns the invariant everyone took for granted, the one saying an account never has two active subscriptions. It isn’t enforced anywhere. A plan switch that fails halfway could, in principle, leave both the old and the new subscription active.
Neither finding is dramatic. Both are exactly the kind of detail that turns a two-week feature into a two-month one when it surfaces late, in production, in front of subscribers. A family plan makes both worse, since it adds members, a shared billing anchor and more ways to switch.
Here the team learns it from a spec instead of an incident. They review the two findings with the business, settle on one rounding rule, decide to enforce the invariant, and build the family plan on rules they now agree on.
After the spec
A reverse specification is a starting point. For Streamly, it supports three kinds of work.
Changing the software without fear. The family plan is simulated against the spec before anyone writes code, and the impact report lists what it touches, what is compatible, what conflicts and what needs testing. It also says what the family plan leaves alone, such as the viewing history or the payment provider integration, which is often what lets a team commit to a date.
Verifying what gets produced, including code written by AI. The validated spec goes to the team’s coding agent through MCP, with each rule and its source, and Lyriks checks the result rule by rule. The rounding fix is either compliant or flagged.
Refactoring or migrating. If Streamly ever rewrites its billing service, the same round trip applies. Old code, spec, business sign-off, new code verified against that same spec.
The Legacy use case page goes through the approach in more detail. If you have a module like Streamly’s, the one everyone tiptoes around, that is a good place to begin, and a single module is enough to hear what your code has been saying all along. To see it on your own code, book a demo.