Methodology
Repave.ai's approach to legacy modernization is opinionated. AI alone is not enough — without the right scaffolding, AI hallucinates business rules, generates plausible-but-wrong code, and produces output that no human can confidently verify. The methodology below is what turns AI from a risky shortcut into a reliable modernization engine.
This document describes how we modernize, and why each step exists. For a catalog of platform capabilities, see repave-features.md.
The Core Problem
Two failure modes dominate legacy modernization:
- Traditional rewrites — slow, expensive, and prone to silently dropping business rules that only existed in the legacy code. Tribal knowledge dies with the team. Years pass before parity is reached, if ever.
- Naive AI rewrites — fast and confident, but hallucinated. Rules get invented, edge cases get smoothed over, and there's no way for a stakeholder to know what was preserved versus what was made up.
Repave's methodology is designed to eliminate both. The throughline is simple: business behavior is the source of truth, captured in a verifiable specification, and every piece of generated code is traceable back to it.
The Six Pillars
1. Feature-First Discovery
We do not start by translating files. We start by extracting business features from the legacy codebase.
A "feature" is a user-meaningful capability — Place an Order, Approve a Loan, Generate End-of-Day Settlement — not a module, class, or screen. Features are the unit at which business stakeholders think, prioritize, and verify. They are also the unit at which modernization risk lives.
Discovery uses static analysis, dependency graphs, UI flow inspection, and AI inference to surface a feature list grounded in what the legacy system actually does. Each feature is linked to the exact files, routines, and line ranges that implement it — so nothing is conjured out of thin air.
Why this matters: modernization is a business decision before it is a technical one. A feature list is something a Product Manager can prioritize. A file list is not.
2. Gherkin+ — Specifications That Cannot Hallucinate
Every feature is specified in Gherkin+, our extension of the standard Gherkin BDD format.
Standard Gherkin gives you Given/When/Then scenarios written in business language. Gherkin+ adds two things that make it verifiable:
- Legacy code associations — every scenario links to the specific legacy source files, routines, and line ranges that implement the behavior it describes. Readers can jump from a
Then the customer is charged 5% taxline directly to the legacy function that calculates it. - Bidirectional traceability — the platform tracks both directions: spec → code (what implements this rule?) and code → spec (what behavior does this routine contribute to?).
This solves the single biggest problem with using AI for specification extraction: hallucination. When every claim in the spec is anchored to a citation in the legacy code, a developer or QA engineer can verify the spec is correct in minutes instead of trusting the AI blindly.
Why this matters:
- The spec is the contract that the modernized code must satisfy. If the spec is wrong, the rewrite is wrong.
- Gherkin+ makes the spec auditable. A reviewer doesn't have to read the AI's mind — they can read the citations.
- Once the spec is verified, the rest of the pipeline can trust it.
3. Completeness — No Business Logic Left Behind
Verifying a spec is correct is not enough. We also have to ensure the spec is complete — that no business behavior in the legacy system is missing from the feature list.
Completeness is enforced through:
- Coverage analysis — every legacy file, routine, and code path is checked against the feature list. Anything not covered by a feature is surfaced as a gap.
- Gap analysis — orphaned files and uncovered branches trigger AI-driven proposals for new features or scenarios to close the coverage.
- Dynamic and static coverage — we measure both what the code contains and what the code executes during representative runs.
The spec is not considered complete until coverage is closed. This is the difference between "the rewrite implements the features we found" and "the rewrite implements everything the legacy system actually does."
Why this matters: the silent failure mode of legacy modernization is forgetting the rare-but-critical edge case — the year-end batch quirk, the regulator-mandated rounding rule, the special handling for one customer segment. Coverage-driven completeness is how we surface them.
4. BDD-Driven Implementation
Once the spec is verified and complete, implementation is driven by the spec, not freestyled by AI.
Each Gherkin+ scenario becomes an executable BDD test. The AI implements the modernized code, and the BDD test suite is the gate: code is not accepted unless every scenario passes. The same scenarios double as the regression suite forever after — characterization tests on day one, regression safety net for the lifetime of the system.
The implementation orchestrator runs the full lifecycle in isolated git worktrees: AI implementation → unit tests → BDD tests → regression tests → merge. Selective scenario implementation may validate only the in-scope scenarios while work is still being accumulated; the merge gate always runs the full suite before merging. If that pre-merge full-suite gate fails, the merge workflow queues a comprehensive fix job before any git merge is attempted. Validated feature branches merge into the Repave integration branch (repave by default), so users can review and promote changes to the modernized main branch through their normal PR flow.
Why this matters:
- The AI cannot drift. Every output is checked against an executable specification that was already verified by humans.
- "It works" is not an opinion — it's a passing test suite tied to business-readable scenarios.
- Refactors and new features land safely because the same suite catches regressions.
5. Verification Without Test Data or Test Environments
Traditionally, getting Product Managers, Developers, and QA engineers to verify a modernized application requires a staging environment, seed data, and a deployment pipeline. That setup is expensive, often impossible, and always slow.
Repave eliminates the prerequisites:
- Interactive UI prototypes are generated directly from Gherkin+ scenarios, runnable in the browser with no backend, no database, and no seed data. PMs can click through user flows the day the spec is verified.
- Test replay captures every scenario execution as an inspectable trace. Reviewers see exactly what happened — inputs, outputs, intermediate state, assertions — without re-running anything or needing infrastructure access.
- API playground (Swagger UI) lets developers exercise generated APIs interactively, again without a deployed environment.
This collapses the verification feedback loop from days to minutes and removes the operational burden of standing up test environments.
Why this matters: stakeholder verification is where most modernization projects bottleneck. If verifying takes a week, nobody verifies. If verifying takes minutes, everybody verifies.
6. Iterate, Then Extend
Once stakeholders can verify the deliverable easily, feedback becomes cheap and frequent. Repave is built around tight conversational feedback loops:
- UI prototypes refine through chat-based feedback, with a component picker so users can point at exactly what they want changed.
- Scenarios, API specs, and implementations all support iterative refinement — not one-shot generation.
- Every change goes back through the same BDD gate, so iteration cannot silently break what was already verified.
And because the same Gherkin+ + BDD pipeline that handled the legacy extraction also handles net-new features, the methodology doesn't stop at parity:
- Users describe a new business requirement in plain language.
- Repave helps them author it as a Gherkin+ specification.
- The same BDD-gated implementation pipeline builds it.
- The high coverage from the modernization effort means new features land without fear of breaking unrelated parts of the system.
Why this matters: modernization is not the goal. Modernization is the foundation that makes future change cheap. A system you can confidently change is worth far more than a system that was merely rewritten.
The Throughline
Every pillar reinforces the same principle:
Make business behavior explicit, verifiable, and traceable — then let AI do the heavy lifting inside that envelope.
- Feature-first discovery makes behavior explicit at a business level.
- Gherkin+ makes the spec verifiable (citations) and traceable (bidirectional links).
- Completeness analysis ensures the spec is exhaustive.
- BDD-driven implementation ensures the code conforms to the spec.
- Prototype/replay-based verification ensures stakeholders can confirm the deliverable cheaply.
- The same loop handles iteration and new features, so the investment compounds.
Without the spec scaffolding, AI is a liability. With it, AI is the fastest path to a modernized system that everyone — PM, Dev, QA, and the business — can trust.
How This Differs From Alternatives
| Approach | Behavior preservation | Verifiability | Speed | Risk |
|---|---|---|---|---|
| Manual rewrite | Depends on tribal knowledge | Manual review only | Slow (months–years) | High — silent rule loss |
| Lift-and-shift | Preserved by accident | None (no spec extracted) | Fast | High — tech debt carried forward |
| Naive AI rewrite | Hallucinated | None — AI output trusted blindly | Fast | Very high |
| Repave methodology | Captured in Gherkin+ with legacy citations | Spec verifiable in minutes; implementation BDD-gated | Fast | Low — every claim is traceable, every change is tested |
Further Reading
repave-features.md— full catalog of platform capabilities, organized by feature