Docs / Hand-off & history

Creating a new version

When the requirements behind a feature genuinely change after it has moved past draft, you create a new version rather than editing the work that was already reviewed. A version captures a real change in intent, and runs the whole workflow again so the new plan gets the same two sign-offs the first one did.

When to create a version

Reach for a new version only when the business requirements have actually changed: a new constraint from legal, an expanded scope, a different acceptance criterion. It is not the tool for fixing a misread or a wording slip while an artifact is still under review.

During review, before an analysis or canvas is approved, comment or edit a section in place. Those changes belong to the version you’re already in; you don’t need a new one.
After the intent itself changes, when the ask is now different from what an earlier version planned for, create a new version so the change is recorded as a deliberate step with its own plan and approvals.

The “New version” button appears once a feature has left draft (it is not offered on a draft or while analysis is generating). A draft is still freely editable in place; there is nothing yet to freeze, so you just keep refining it.

A new version isn’t only started by an author. A reviewer choosing Reject & rework at a gate also creates the next version, with the AI regenerating from the reviewer’s reason and comments instead of an author editing the definition by hand. See reviewing & approving.

Who can create one

Versioning a feature is an authoring action: the feature’s own author can do it, and so can tech reviewers and admins (whose capabilities include everything an author can do). An observer can read and comment but cannot start a new version.

What happens, step by step

Open the feature and choose New version. A dialog asks why the new version is needed; a short reason is required, and it is saved to the feature’s version history.
Confirm. The previous version is frozen, with its definition, analysis, canvases, and approvals left exactly as they were, and a new version is created from a copy of the previous version’s definition.
The definition opens in the editor, pre-filled with the carried-forward fields. Edit anything (goal, scope, services, acceptance criteria, constraints) to reflect the new requirements.
Save it as a draft to keep working, or submit it for analysis to start a fresh pass: a new analysis document, a new canvas per service, and both review gates again.

A new version starts in draft, just like a brand-new feature, and follows the same lifecycle from there. Because every canvas and analysis is approved fresh, the new version’s plan is judged on its own merits, and an earlier approval doesn’t carry over.

Earlier versions stay intact

Creating a version never overwrites what came before. Each version keeps its own analysis and its own set of canvases, stored separately, so you can switch back to an older version and see exactly what was planned and approved at that point, read-only, since approved artifacts and older versions are locked. The generation preview always exports the current version’s approved plan.

Why this exists

Treating a real requirement change as a new version, rather than an edit to approved work, is what keeps the history meaningful. Every version marks a deliberate shift in intent, with a reason attached and its own sign-offs, so the record reads as a story of decisions rather than a pile of overwrites. And re-running both gates means a changed requirement gets the same scrutiny the original did: no requirement reaches code on the strength of an approval that was given for something else.