Documentation

The Four Stages

Specify's workflow moves features through four stages: Plan, Review, Create, and Finalise. The order is deliberate - each stage builds on what the previous one established, and each produces something the next stage needs.

Why this order

The four stages follow a natural progression: capture → validate → define → lock.

You can't validate something that hasn't been captured. You can't fully define something that hasn't been validated. And you can't lock something that hasn't been fully defined. Each gate prevents work from being wasted on features that shouldn't exist or aren't ready.

This doesn't mean you have to finish one stage for all features before starting the next. Features move through stages independently. You might have some features in Finalise while others are still in Plan. The stages provide structure, not a waterfall.

Plan: capture

What happens: Features are added with a name and description. Quick capture - get the ideas in, refine later.

What it produces: A list of proposed features, each with a P-number as a planning identifier. This is the brainstorming output - everything the team thinks the system might need.

Key principle: Progressive refinement. A feature doesn't need to be complete to exist in the Plan stage. A name and a rough description are enough to start. Stakeholders discuss, add comments, and decide whether each feature is necessary.

Exit criteria: A feature is nominated for review - the team agrees it belongs in the project.

Review: validate

What happens: Nominated features are prioritised (MoSCoW), categorised (metadata assigned), and either approved, rejected, or held.

What it produces: Approved features with permanent F-numbers, each with priority and classification metadata. The team now knows what's Must Have vs Could Have, and how each feature fits into the system's technical architecture.

Key principle: Forced decisions. MoSCoW priority makes the team choose - is this truly a Must Have, or is it a Should Have that feels important? The 60% rule (Must Haves should be ≤60% of total) keeps prioritisation honest. Rejection and Hold are valid outcomes - not every proposed feature belongs in the project.

Exit criteria: A feature is approved with complete categorisation.

Create: define

What happens: Approved features are organised into feature sets. Use cases and requirements are added. Custom ordering and naming conventions are applied.

What it produces: The full behavioural definition - feature sets containing features, each with feature requirements, use cases, and use case requirements. This is the specification.

Key principle: Completeness through structure. The two-level requirement hierarchy (feature requirements for general rules, use case requirements for specific scenarios) ensures nothing falls between the cracks. Custom ordering means the specification reads in the order that makes sense for the system, not the order things were created.

Exit criteria: The feature's specification is complete - all requirements are written, all scenarios are covered, nothing is vague.

Finalise: lock

What happens: Complete specifications are reviewed, signed off, and locked. The specification can be exported.

What it produces: A locked, exportable specification that serves as the contractual basis for implementation. JSON, CSV, and PDF exports preserve the full hierarchy and custom ordering.

Key principle: Deliberate commitment. Signing off means the team agrees: this is what we're building. Locking prevents accidental changes to a specification that may already be in development. Unlocking is possible but requires explicit authorisation.

Exit criteria: The feature is signed off and locked.

Feature states

As features move through stages, their state changes:

PlanningNominatedApprovedCategorisedFinalised

Features can also be Held (parked in Review for later decision) or Rejected (not needed for this project). The state is always visible, so the team can see at a glance where every feature stands.

Not waterfall

The four stages provide structure, but they don't require sequential, phase-gate execution. You can:

  • Start with one feature set and build out as you go
  • Add three new features to an existing product without specifying the whole system
  • Have features at different stages simultaneously
  • Go back and add more features to Plan while others are in Create
The stages ensure quality - every feature goes through the same rigour. But the order in which you work through features is up to you.

Related