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 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-nnn links 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-scenario says 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.

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.

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.

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.

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.

Next: Implementing a feature.