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.

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.

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.

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.

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.

Next: Implementing a feature.