Reversa: A Reverse Documentation Engineering Framework for Converting Legacy Software into Operational Specifications for AI Agents
This paper introduces Reversa, a multi-agent framework that reverse-engineers legacy software into traceable operational specifications for AI agents by extracting implicit rules, explicitly marking confidence levels, and preserving gaps for human validation, as demonstrated in a case study migrating an ATM system from COBOL to Go.
Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer
Imagine you have an old, dusty library filled with thousands of handwritten books. These books contain the rules for running a bank, but they are written in a language no one speaks anymore (like COBOL), the ink is fading, and there are no table of contents or indexes. The original authors are long gone, and the only people who know how to read them are a few very old librarians who are retiring.
Now, imagine you want to hire a team of super-smart, fast robots (AI agents) to rewrite these rules into a modern language (like Go) so the bank can run on new computers. The problem? If you just tell the robots, "Go fix this," they might guess wrong. They might think a rule means one thing when it actually means another, and the bank could crash.
This paper introduces Reversa, a new framework designed to solve this exact problem. Think of Reversa not as a magic wand that instantly translates code, but as a specialized "Reverse Documentation" factory.
Here is how it works, using simple analogies:
1. The Problem: The "Silent" Legacy System
Old software systems are like a house where the owner left 20 years ago. The lights are still on, the fridge is humming, but nobody knows why the kitchen light is wired to the front door, or what happens if you turn on the oven while the washing machine is running. The rules are hidden inside the walls (the code). If you try to renovate without knowing these hidden rules, you might accidentally knock out the power to the whole neighborhood.
2. The Solution: A Team of Specialized Robot Detectives
Instead of asking one robot to read the whole house and guess the rules, Reversa sends in a team of specialized agents, each with a specific job, like a production line:
- The Scout: Walks around the house first. "Okay, there are 5 rooms, a basement, and a weird door in the kitchen." (Maps the project surface).
- The Archaeologist: Digs into the walls. "I found a blueprint here that says this pipe connects to that valve." (Analyzes modules).
- The Detective: Looks for clues. "Why is the light wired to the door? Ah, the notes say it's a security feature." (Extracts hidden business rules).
- The Architect: Draws a new map based on what was found. "So, the kitchen is the heart of the house, and the basement holds the water." (Synthesizes architecture).
- The Writer: Writes down the rules clearly. "Rule #1: If the door opens, the light turns on." (Writes specifications).
- The Reviewer: The most important one. They check the Writer's work. "Wait, did we find a note about the light? No? Then we can't say for sure. Let's mark this as 'Maybe' or 'We need a human to check this'." (Reviews confidence and gaps).
3. The Secret Sauce: "Confidence" and "Gaps"
Most AI tools try to sound 100% sure, even when they are guessing. Reversa is different. It uses a traffic light system for every rule it finds:
- 🟢 Green (Confirmed): We found this in the code. It's a fact.
- 🟡 Yellow (Inferred): We didn't find a direct note, but the pattern suggests this. It's a smart guess, but be careful.
- 🔴 Red (Gap): We have no idea. The code is missing this info. Stop! A human needs to come here and tell us what to do.
This is crucial. It prevents the robots from confidently making mistakes. It tells the human, "We know 97% of the rules, but here are the 3% where we need your help."
4. The Result: A "Contract" for the Robots
The output isn't just a boring manual for humans to read. It's an operational contract for the AI agents. It says:
- "Here is what the system does."
- "Here is the proof (which file in the old code we found it in)."
- "Here is what we don't know yet."
This allows the AI agents to safely rewrite the old system (migrate from COBOL to Go) because they have a clear map and they know exactly where the "fog of war" is.
5. The Real-World Test: The ATM Machine
The authors tested this on a real (but simple) project: an old ATM machine written in COBOL that needed to be rebuilt in Go.
- The Process: They ran the Reversa pipeline.
- The Output: The system produced 517 "claims" (rules). It marked 490 as facts, 24 as guesses, and found 3 missing pieces (gaps).
- The Human Role: Humans stepped in to resolve the missing pieces and the "guesses."
- The Outcome: They created a plan to rebuild the ATM and wrote 53 test scenarios (like "If I put in $20, I should get $20 back"). They successfully started the rebuild, completing 9 out of 11 major tasks.
What This Paper Does Not Claim
It is important to know what this paper doesn't say:
- It does not say this is perfect or that it works for every single old system in the world yet.
- It does not claim that the robots can do the whole job without humans. Humans are still needed to fix the "Red" gaps.
- It does not claim that this is faster or cheaper than doing it the old way yet. They only proved it's possible and that it creates a safer, more organized process.
In Summary
Reversa is a framework that treats old software like a crime scene. It uses a team of AI detectives to carefully map out what the system does, explicitly marking what they are sure of and what they are guessing. This creates a safe "instruction manual" that allows new AI robots to update or rewrite old systems without breaking them, while keeping humans in the loop to solve the mysteries the robots can't figure out.
Drowning in papers in your field?
Get daily digests of the most novel papers matching your research keywords — with technical summaries, in your language.