Deciding the to-be specification
This is the step the rest of the work depends on, and the one that is genuinely yours. The as-is records what the legacy system does. The to-be records what the new one will do. Agents implement against the to-be and the same scenarios verify the result, so a behaviour that is not here does not get built.
Before you can write to-be scenarios
To-Be Gherkin generation requires a complete To-Be architecture. This is a gate, not a suggestion, and it is visible in the feature view: scenarios written against a design that does not exist yet would be describing a system nobody has decided on.
The to-be architecture describes the modern design — its components, its boundaries, and the target stack the agents are told about. Where your installation has clarification enabled, requirements are clarified with you before the to-be architecture is generated. Each answered round, and the Clarification History kept with the finished design, names who answered it.
The domain model
The to-be is written against one domain model of the new application, kept on the Domain page (Design & Architecture). It names the business's areas (subdomains, each core, supporting or generic) and the things in each that the business has and changes as a whole (aggregates), with their states, the changes between states, and the entities and fields they hold. The terms are Context Mapper's, and Download CML gives the model as a Context Mapper file.
You do not draw it first. The agent builds it while it writes the to-be: it reads the model, reuses what fits, and adds what a feature needs. Every to-be scenario names the aggregates it reads or changes:
# @aggregates: ["Allocation", "Room"]
Scenario: Check a student in to their room
A scenario that only changes what the screen shows, marked # @no-api, names none. Each scenario
card shows its aggregates; each opens that aggregate on the Domain page.
The API is built from the model too. An endpoint is an aggregate (/allocations), one of its entities
(/allocations/{id}/charges) or one of its state changes (POST /allocations/{id}/check-in), grouped
by subdomain. The agent adds only the endpoints its scenarios use. Repave refuses any other new
endpoint, so the agent adds what is missing to the model first, and asks you when it cannot tell
which business thing a behaviour belongs to. Endpoints a project already had stay as they are.
Switch the Domain page from List to Diagram to see the model drawn: each subdomain is a
region, each aggregate a card, and an arrow runs wherever one aggregate refers to another. Almost
everything refers to users and lookup lists, so an arrow into a Generic subdomain is left out; the
card's last line names it instead (→ User). Click an aggregate to see all of its arrows, read its
detail beside the picture and edit it from there.
On the Domain page you can correct what the agent built:
- add, edit and delete entries; edit an aggregate's states, state changes and fields;
- move an aggregate to another subdomain, which changes no scenario;
- rename an aggregate, which renames it in every to-be scenario that names it (the dialog says how many first);
- merge one aggregate into another, which retags its scenarios and moves its entities over.
An aggregate that scenarios name cannot be deleted; merge it instead. Agents can add and update entries but never rename, move, merge or delete them.
Features whose to-be was written before the Domain page existed are not changed. The next time a feature's to-be is generated or edited, its scenarios are tagged.
The three things you can do with a behaviour
Keep it. The to-be scenario says what the as-is said, written against the new design.
Change it. The to-be scenario says something different. This is where modernization actually happens — the legacy behaviour was a product of its constraints, and most of those constraints are gone.
Mark it as not required. Legacy behaviour that should not survive is recorded as deliberately dropped. This matters more than deleting it silently: a reviewer later can see the decision was made rather than wondering whether the behaviour was missed.
How a to-be scenario traces back
Every to-be scenario either traces to as-is scenarios or is explicitly new — never both.
# @from-asis: ASIS-nnnlinks it to the legacy behaviour it derives from, and several ids can be listed where one new behaviour replaces more than one old one.# @new-scenariosays this is behaviour the legacy system never had.
To-be scenarios carry their own stable ids (# @id: TOBE-n) and, deliberately, never carry
@code-ref: a to-be scenario describes behaviour that does not exist yet, so a pointer into the
legacy source would be a claim about the wrong codebase.
The cross-links work in both directions in the UI, and each to-be scenario shows its link status — linked to as-is, matched by title, link missing, or new behaviour — so drift is visible while you are editing rather than discovered later.
Every scenario card, on As-Is and To-Be, shows its own id (TOBE-012, ASIS-007) beside
its number. The number is only a count of the scenarios currently shown, so it changes when you
filter or search; the id does not, which makes it the one to quote and to look up in Mapping.
Hovering the link badge names the counterpart scenario by its id.
Seeing the whole mapping
The Mapping tab, next to As-Is and To-Be on a feature's scenarios, shows every as-is scenario beside the to-be scenarios that trace to it, one row per group. A row can be a straight pair, a Split (one legacy behaviour became several), or a Merged row (several became one). After the as-is rows come the to-be scenarios with no legacy source: those whose link is broken, then the new behaviour. Mapping is available once a feature has both an as-is and a generated to-be, and the tab says why when it is not.
The buttons above the rows filter them: Mapped, Unmapped, Not required, Broken links and New. A to-be scenario that names one real as-is id and one that does not exist stays Mapped and is also listed under Broken links, which no other screen reports. Click a row to read both sides in full, side by side, with the Rule and the Background steps each one inherits. Expand all opens every row the filter shows. Open in As-Is and Open in To-Be take you to that scenario on its own tab. When you come back to Mapping, the filter and the open rows are as you left them.
Once a feature is implemented, a mapped row whose as-is scenarios cite legacy code and whose to-be scenarios have mapped code carries Compare code. It opens the pair's code side by side, filling the window: the legacy code on the left, the modern code on the right. Each side lists all of its files one after another, so you read them by scrolling: each file shows the lines its scenarios name, highlighted, and the modern side lists what each range does. The two sides scroll separately. When a side has more than one file, the file buttons at its top jump straight to a file. Each button shows the file's name; two files with the same name also show enough of their folders to tell them apart. The arrow beside a file's name folds its code away until you open it again. Open the lines around a range with the arrows, or the whole file with Full file. A row with no code on one side, or a feature whose code has not been mapped yet, has no Compare code.
You can fix what the view shows without leaving it:
- Add To-Be scenario, on an unmapped row, adds a to-be scenario that traces to that as-is scenario. The Rule is filled in for you: it is the one where most of the scenario's siblings went, and you can change it. Describing what should change is optional. Left empty, the agent carries the legacy behaviour over as it is. The link is set by the platform as the scenario is saved, so the row becomes Mapped when the agent finishes. A scenario that could not be linked, for example because another scenario already has its title, is never saved: the agent is told why and can choose another title, and if it cannot, the run fails without changing the to-be.
- Not Required and Mark as Required are the same decision as on the As-Is tab.
- Update, on a broken or title-matched link, opens the scenario editor for that to-be scenario.
Project viewers see the mapping without these actions. On a completed feature, Add To-Be scenario and Update ask to reopen it first, as every other edit does.
Writing at the right level
You can generate to-be Gherkin for a whole module at once, then refine it, or write scenarios yourself. Rules and scenarios are both editable, and a to-be block can be validated without being written, which is useful when you are drafting something you are not sure about.
Reviewing a module's to-be
A module's Gherkin tab lists its features on the left, under Generate To-Be for the module, which generates the to-be of every feature you tick. The one you select shows on the right exactly as its own page's Gherkin tab does, with nothing left out: As-Is, To-Be and Mapping, each scenario's references, approving and revoking, Refine, selecting scenarios to implement or test, and the actions menu.
The view you pick stays as you move from feature to feature, so you can compare the same document across the module. A feature without both documents has nothing to map, so it shows its to-be (or its as-is) until you select one that can map again. Approve all To-Be scenarios, above the list, approves every scenario of every feature in the module that is not locked.
The feature's name above its scenarios opens its own page, where its Decisions, Test Results and other tabs are. Answer pre-flight takes you to that page's Decisions tab.
Talking to the agent while it writes
Like every agent, the to-be generation agent can ask you a question when the design, the as-is scenarios and the modernized code do not settle a decision, and it reads what you type in its chat while it works. See Talking to an agent while it runs.
Scenarios the agent suggests
After it writes the to-be, the generation agent looks for what the to-be does not cover yet: legacy behaviour nothing carries forward, error paths the legacy code handles, the edges of a rule that only has its happy path, and permission checks. When it finds some, Suggested Scenarios (n) appears beside Add Rule at the top of the to-be.
Open it to see each suggestion under the rule it belongs to, with the agent's reason for it. Every suggestion starts ticked: untick the ones you do not want and choose Add. The ticked scenarios are added to the to-be, unapproved like any scenario you add yourself, and the rest are dismissed. A suggestion for a rule the to-be does not have yet adds that rule. Cancel keeps them all for later.
A suggestion is checked against the to-be exactly as a scenario you add yourself would be — its annotations, its references to your registries and tables, and the to-be's own rules. If the to-be has changed since the agent made a suggestion so that it no longer fits (a scenario with the same name now exists, say), it is shown as Can't be added with the reason, and nothing half-applies: either every ticked suggestion is added, or none is. Generating the to-be again replaces any suggestions you had not dealt with.
Scenario titles are identity. Ids are carried forward by matching titles, so renaming a scenario mid-flight is the one edit to be careful with. The platform reports a changed title as a rename, naming the before and after, rather than as a scenario that vanished.
Changing a scenario takes away its approval, and only its own. However the change is made, in the scenario editor, by an agent, by moving scenarios between features or by a feature file synced from the repository, a scenario whose steps changed needs approving again, and every scenario you did not change keeps its approval. A renamed scenario counts as changed, and so does every scenario under a feature or Rule Background you changed. A scenario moved to another feature arrives there unapproved.
Dependencies between features
Feature Dependencies records what has to exist before what. This is worth setting before you start implementing: the order work happens in is otherwise a guess, and a feature implemented against another that does not exist yet produces scenarios that cannot pass.
Validation rules
Validation rules are the standards every implementation is checked against — your own, plus a built-in code-review-style set every project starts with. A rule targets feature implementation, the UI prototype, or both. Rules that conflict are surfaced rather than silently resolved, and the Validation Rules page shows which jobs a conflict is holding up.
Adding a feature to an existing app
A project that maintains an existing app, or builds a new one, has no as-is to keep, change or drop: each feature starts from what you ask for. On the Features page, choose Add feature, describe what the feature should do under What should it do?, and choose Write scenarios. A feature name and supporting documents (PDF, DOCX, TXT or MD) are optional. Repave reads your codebase, writes to-be scenarios that name your app's screens, fields and messages the way the app already does, and the feature appears on the list with its to-be ready for you to review. Its page opens on the To-Be view; there is no As-Is.
Add feature waits until your codebase has been cloned, or, for a new app, until its foundation pull request has merged, and its tooltip says why while it waits. A request that spans distinct areas may become more than one feature. Approve, edit and implement their scenarios as for any other feature.
When the project already has a feature the request extends, such as one imported from your repository's feature files, Repave adds the new scenarios to that feature instead of creating a second one, and the feature reopens for review. One request can extend several features and add a new one. When a person can answer the run and Repave cannot tell which feature a request belongs to, it asks you in the run's chat, naming the candidates and "A new feature"; your answer is final. Implementing scenarios on an imported feature changes only those scenarios in its file: the rest of your file, and its layout, stay exactly as you wrote them.
When the to-be is ready
Every scenario should be one you would accept as a description of the new system, because that is exactly how it will be used. Once implementation starts, the to-be specification is the contract.
Approve each scenario you accept with Approve on the scenario, or select several and choose Approve n on the bar that appears. To find the ones still waiting on a long list, open Filters and pick Not approved (n) from All approvals; the counts beside Approved and Not approved say how many of each there are before you choose. Select all then selects just the scenarios the filter shows. The filter is on the To-Be view only, and is remembered for the feature like the other filters.
An approved scenario's badge names who approved it: Approved by Jane Lee. Click the badge to open the scenario's history, where the approved version says when. A scenario approved before Repave kept the approver, or approved by importing its feature from the repository, reads just Approved, and its history gives the date only.
Next: Implementing a feature.