From Code to Specification

Anyone who wants to replace, modernize, or tender a system that has grown over the years usually starts with the question of what the new system should be able to do. That is the wrong order. The only complete description of what an organization actually does today lives in the existing system: in the source code and in daily operation. This article shows how we reconstruct requirements from the existing system, what an as-is specification must contain, and how a robust to-be specification emerges from it.

Why the as-is comes before the to-be

In the first article of this series, I described why legacy systems are a knowledge archive: the knowledge of colleagues who retire is not in documents but in custom code. A practical consequence follows for every modernization initiative: before anyone describes how things should be, it must be evidenced how they are.

In practice, the opposite often happens. A replacement project starts with to-be workshops. The business describes what it wants from the new system, IT adds architecture guidelines, and the legacy system is considered known because people use it every day. The requirements document that results is a collection of wishes and memories. The special cases the legacy system has accumulated over twenty years are not in it: the rounding rule for a particular contract type, the exception for a single key account, the interface that generates a report for accounting overnight. They only surface when the new system can no longer handle them, usually during acceptance or after go-live.

Three things only an evidenced as-is specification provides:

• Completeness of the rules. The legacy system contains every business rule that applies today, including the rules nobody can explain anymore. Workshops deliver the rules somebody remembers.
• Interfaces and data flows. Which systems read and write which data, which batches run at night, what depends on what? That is written nowhere except in the code.
• A basis for estimation and tendering. Without the as-is, scope is estimated; with the as-is, it is counted. For tenders, that is the difference between vendors' risk premiums and a calculable offer.

For us, this is a direct application of the principle "Own the Spec, not the Code". With existing systems, the organization usually owns neither: not the code in an understandable form and not the specification. The first step is therefore reconstruction.

Whoever does not own the as-is writes the to-be from memory.

Two paths into the existing system: source code and usage

Requirements can be reconstructed from two sources, and both have their place. We use two agentic platforms for this, both part of our consulting service.

Whitebox: from the source code. SLIP, the Sysparency Legacy-Code Intelligence Platform, reads in the source code and existing documentation of a system regardless of technology: SAP/ABAP, IBM mainframe with COBOL, PL/I, and JCL, IBM i, NATURAL/ADABAS, or open systems such as Java, Python, C/C++, and JavaScript. The order of analysis is decisive. First, a deterministic, symbolic analysis establishes the facts: call and dependency graphs, read and write access to data, screen and process flows, interfaces, and jobs. Only then do AI agents explain every component twice, in business terms for the business side and in technical terms for architecture and development. The AI does not invent a structure; it explains a proven one. Every statement is traceable down to program and line.

Blackbox: from observed usage. App2Spec looks at the system the way users see it. Either an AI agent operates the application autonomously and explores screens, dialogs, and navigation paths, or the platform records the work of real users, every screen and every event including a screenshot. From this emerge screens, controls, navigation paths, data fields, derived business rules, and end-to-end processes with process diagrams. Every statement is backed by a screenshot and an event log.

Which path is right depends on the situation:

In our projects, the third case is the most common. The code says what a system can do; usage says what of it is needed. Only the combination reveals which functions nobody has called in years and which rule is applied a hundred times a day. Both matter for the to-be, for opposite reasons.

What an as-is specification must contain

An as-is specification is neither an annotated code listing nor a collection of screenshots. It is a business description of the system in a structure that serves the next steps: tendering, to-be design, migration, or agentic redevelopment. In our projects, a fixed structure has proven itself:

1. Processes. End-to-end flows from trigger to result, as a process diagram and in text form, with the roles and systems involved.
2. Screens and controls. Every screen with its fields, actions, and navigation paths, so that it is visible what users actually do.
3. Data objects and fields. Which data the system holds, where it originates, who reads it, and who writes it.
4. Business rules. Validations, calculations, permissions, and special cases, each with the condition under which it applies.
5. Interfaces and batches. Inbound and outbound connections, overnight processing, dependencies between jobs.
6. Evidence per statement. Program and line or screenshot and event log, accessible directly from the specification.

The last point is the most important. A specification is only worth as much as the trust it enjoys. When the business questions a business rule, nobody should have to argue about who remembers correctly. One click shows the source. For audit, tendering, and acceptance, that is the difference between an opinion and evidence.

Because both platforms store their results in a knowledge graph with typed, standardized entities, as-is specifications are structured uniformly across applications. That pays off as soon as more than one system is affected, for example in a landscape analysis or a consolidation.

What no tool can decide, people decide. Our experts validate the specification together with the business at the points where business truth matters. The typical question is: Is this rule intended, or is it a defect that became a habit over the years? The code does not know the answer. It only knows that the rule exists.

From as-is to to-be: the delta question

With an evidenced as-is specification, the character of the to-be workshops changes. The question is no longer "What do you want?" but "What of this do we keep, what do we change, what do we drop?". An open elicitation becomes a delta decision that the business makes on the basis of facts.

• Keep. The majority of business rules carry the business and are adopted unchanged. They move one to one into the to-be, with their evidence from the as-is. In our experience, this is the largest part of the scope, and exactly this part is missing from requirements documents that originate in workshops.
• Change. Known pain points, new regulatory requirements, changed processes. This is where the actual business work happens, but now against the backdrop of a complete starting position.
• Drop. Functions that, according to the usage recording, nobody calls anymore, historical special cases without an active use case, interfaces to systems that no longer exist. Dropping is the cheapest decision in the whole project, and it is only possible with an evidenced as-is.

Technically, we load the as-is specifications from App2Spec and SLIP into the ReqPOOL Requirements Manager and evolve them there into the to-be specification. reqChecker checks every requirement against the criteria of IREB and ISO/IEC/IEEE 29148 for unambiguity and verifiability and suggests testable wording. The result is a specification that serves two audiences: as a requirements document for a tender in which vendors calculate on facts instead of risk premiums, or as a machine-readable build order for agentic redevelopment with reqCoder, our complete, fully automated agentic Software Development Lifecycle, which is already in use internally at ReqPOOL.

What concretely changes in the project

I am often asked whether reverse engineering does not lengthen a project. Our experience from ReqPOOL projects shows the opposite: it shortens the project, because it moves the most expensive phase to the front. The special cases are found at the beginning, not during acceptance. Three things change visibly:

• Capture takes days, not months. Source code extraction and recording sessions run agentically. The analysis of a system that manually requires months of workshops and documentation is available in days, based on our experience from ReqPOOL projects and verifiable per project. The effort of people concentrates on validation.
• Workshops become shorter and better. Instead of describing the system from memory, the business reviews an evidenced description and decides on the delta. The discussions revolve around decisions, not facts.
• The knowledge stays in the organization. Documentation, knowledge graph, and assistant remain with the client as working tools. The next question, "What breaks if we change this?", is no longer put to the one person who still knows, but answered in seconds from the knowledge graph.

For regulated industries, there is the added assurance that both platforms are hosted in the EU, that client data and source code are not used to train AI models, and that ReqPOOL consulting projects incur no license costs for the tools used. You pay for expertise and effort; the as-is specification belongs to you.

The next step

When a replacement or modernization initiative is on the horizon, the evidenced as-is specification is the first step, and it comes before the first to-be workshop. How we reconstruct existing systems from source code and usage is described in our service Reverse Engineering; the two paths in detail are on the pages for App2Spec and SLIP. In an expert conversation, we clarify which of your systems is suitable for a start and whether the whitebox path, the blackbox path, or both are appropriate.