Skip to main content
Version: 0.1.148

Reviewing the as-is specification

The as-is specification is the record of what your legacy system does today, written as Gherkin scenarios and extracted from the code. It is the thing everything else is built on, so it is worth the read.

What a feature is here​

A feature groups scenarios that belong to one piece of behaviour. Features are discovered per module, and each carries a title, a description, and the scenarios themselves.

Where a feature's title has no Latin letters, it also carries an English name. That is not cosmetic: branch names are derived from titles, and a title that slugs to nothing would produce a branch nobody can work with.

The English name shows under the feature's title, and the pencil beside it edits it at any time. Before the feature has a branch, saving only stores the name. Once it has one, the dialog shows the branch the new name gives it, and Save and rename branch renames that branch too — here and on your remote. That is refused while a pull request is open on the branch: close it first. Renaming the feature's title never moves its branch.

Reading a scenario​

A scenario describes behaviour from the outside — what a user does, and what the system does back. Two annotations matter when you are reviewing:

  • # @id: ASIS-nnn is the scenario's stable identity. Ids are never renumbered. Everything that refers to a scenario later — a to-be scenario tracing back to it, a test result, a report — refers to this id, which is why editing a scenario is safe and reordering it changes nothing.
  • @code-ref points at the legacy code the behaviour was read from. The paths are validated, and a scenario's related files open at the annotated lines, so you can check a claim against the source in two clicks rather than searching for it.

That chain — scenario to code and back — is what makes the as-is reviewable rather than something you have to take on faith. It is protected: the links cannot be quietly dropped by a later edit.

Focusing discovery​

Discovery does not have to swallow the whole codebase at once. You can choose individual files as the focus, which is the usual way to handle a large system: run discovery over the area you are about to work on, review it properly, then move on.

Discovering from the running legacy app​

When the project has a legacy desktop app set up and ready (see Running the legacy desktop app), the Discover features dialog has a second button, Discover with legacy app, beside Discover Features. It takes the same focus and options. The difference is where the agent starts: it opens the running app first, maps its screens and reads the data behind them with read-only queries, and only then writes each feature's as-is Gherkin, so the scenarios describe what the app does and not only what the code says. Where the two disagree, the scenario follows the app and says so.

  • Real records are used for their shape, such as lookup values, ranges and formats, and are not copied into scenarios.
  • The agent keeps the screens that show each feature best, naming the scenarios it wrote that each one shows. They appear on the feature's Legacy Screens tab, marked as kept by the agent.
  • If the app's container cannot start, the run fails and says why. It does not quietly fall back to reading code. If the app starts but a screen will not open or crashes, the agent says so and continues from the code for that area.
  • The button is hidden until the legacy app is ready. Discover Features works exactly as before and needs no legacy app.

Refining what came out​

Discovery is a first pass, and refinement improves it. Refinement of as-is Gherkin stays legacy-scoped — it sharpens the description of what the legacy system does and never quietly introduces behaviour you have not asked for. That boundary is the point: the as-is is a record, not a wish list.

When the project has a ready legacy desktop app, the Refine dialog has a checkbox, Verify against the legacy app. Ticked, the same Refine Analysis button starts a run that opens the running app, checks each scenario against it, corrects what the app contradicts, adds behaviour it shows that the as-is misses, and keeps the screens it saw, each naming the scenarios it shows (on the Legacy Screens tab). Your feedback is optional then: with nothing typed, the task is to verify and augment. The as-is is edited directly, as in any refinement, and the usual review still checks it. Real records are used for their shape and are not copied into scenarios. The box is hidden until the app is ready. If the app's container cannot start, the run fails and says why.

You can also edit scenarios directly. A bulk-action toolbar handles the repetitive cases, and the view state persists when you leave a feature and come back, so a long review survives an interruption.

Splitting and merging​

A discovered feature is sometimes the wrong size — two behaviours in one, or one behaviour spread across several. Features can be split, and a feature that has been split is marked as such rather than disappearing.

When the as-is is good enough​

It does not have to be perfect. It has to be true: every scenario should be something the legacy system actually does, and anything you cannot verify against the code is worth deleting rather than carrying forward. The next step turns this record into decisions, and a decision made against a scenario nobody checked is the expensive kind of mistake.

Next: Deciding the to-be specification.