Requirements and scenarios

Write SpecsGraph requirements with stable IDs such as ORD-12, a clear statement and Given, When, Then scenarios that reviewers and agents can check.

Anatomy of a requirement

A requirement states one rule or behavior the system must have. It is a typed node in the graph rather than a paragraph in a document, so each part has a field of its own.

Field	What it holds	ORD-12
ID	The context key plus a number; see Requirement IDs.	`ORD-12`
Title	A short line that fits in a list.	Reserve stock for every line item at checkout
Statement	The rule in one to three sentences, written with glossary terms.	When a Customer starts checkout, the system creates a reservation for the full quantity of every line item before payment is requested.
Context and service	Where the requirement lives on the map.	Orders, Checkout service
State	Proposed, Active or Retired; see State.	Active
Scenarios	Acceptance scenarios written as Given, When, Then.	Two, shown below
Links	Glossary terms, actors, decisions and other requirements it depends on.	Reservation, Customer, BIL-04, the decision Reserve stock before payment

SpecsGraph assigns the next number for the context key when a requirement is first proposed, zero-padded to at least 2 digits, as in BIL-04. Numbers are never reused, even after a Withdrawn proposal or a retirement. A requirement keeps its ID when its text changes and when it moves to another context.

Scenarios in Gherkin

Scenarios are the acceptance criteria of a requirement, written in Gherkin. Given sets up the situation, When is the action, and Then is an outcome you can check. Each scenario covers one path. Most requirements need two to four: the main path plus the edge cases that matter.

ORD-12Gherkin

@ORD-12
Feature: Reserve stock for every line item at checkout

  Background:
    Given the Catalog has 5 units of "Trail mug" in stock
    And the Catalog has 1 unit of "Canvas tote" in stock

  Scenario: Every line item gets a reservation
    Given a Customer has a cart with 2 "Trail mug" and 1 "Canvas tote"
    When the Customer starts checkout
    Then a reservation holds 2 "Trail mug" for the order
    And a reservation holds 1 "Canvas tote" for the order
    And the Catalog shows 3 units of "Trail mug" available

  Scenario: Checkout stops when a line item cannot be reserved
    Given a Customer has a cart with 2 "Canvas tote"
    When the Customer starts checkout
    Then no reservation is created for the order
    And the Customer is told that only 1 "Canvas tote" is left
    And payment is not requested

Write steps with glossary terms and actor names, since SpecsGraph links both. Keep each step about behavior someone outside the code can observe. the reservations table has 2 rows describes an implementation; a reservation holds 2 Trail mug describes the rule.

Requirements and BDD features

Each requirement is one Gherkin feature. SpecsGraph writes the Feature line from the requirement's title and tags it with the ID, as in the example above. You write the scenarios, plus a Background when every scenario shares the same setup.

Behavior bigger than one rule lives a level up. A service groups related requirements the way a feature file with several rules would: Checkout holds ORD-12 and ORD-13, and the Requirements tab lists them together. Workstreams group delivery work, not behavior, so do not use them to group requirements. Domain-driven and behavior-driven foundations covers the BDD background.

Requirements in your repository

When a proposal that adds or changes a requirement is approved, SpecsGraph writes one Markdown file per requirement into the project's spec folder, scenarios included. ORD-12 lands at specsgraph/contexts/orders/requirements/ORD-12.md, in the same repository as the code that implements it.

Because the file lives in Git, you can mention ORD-12 in commit messages and pull requests, name acceptance tests after its scenarios, and review a change to the rule in the same history as the change to the code. Spec files in your repository describes the full layout.

State

Requirement states are separate from proposal statuses. A proposal's status tracks its review; a requirement's state only says whether the requirement is part of the spec.

State	Meaning
Proposed	Exists only in a proposal that is not Published yet. Reviewers can comment on it, edit it and challenge it. It is not part of the spec.
Active	The proposal that added it, or last changed it, is Published. This is the current spec.
Retired	Removed from the current spec by a Published proposal. It keeps its ID and stays in history.

A requirement in a Withdrawn proposal never enters the spec. A change to an Active requirement goes through a new proposal, and the Active version stays in place until that proposal is Published.

Retire a requirement

When a rule no longer applies, retire the requirement instead of deleting it. In the web app, retire it while you edit it in a proposal; an agent drafts the same change with propose_requirement. Once the proposal is Published, the requirement is Retired: its file stays in the spec folder with state: retired, and its ID is never given to another requirement.

Writing good requirements

One rule per requirement. ORD-12 reserves stock and ORD-13 releases it after 15 minutes idle. Kept apart, each can change on its own schedule.
State the rule, not the design. The title of ORD-12 survives a rewrite of the inventory code. A statement like insert one row per line item does not.
Use the glossary. If you need a word the glossary does not have, propose the term in the same proposal.
Link across contexts. BIL-04, Capture payment only once stock is reserved, lives in Billing but depends on ORD-12. Link them so a change to one shows up in reviews of the other.
Record the why. Link the decision that explains the rule. At Northwind, ORD-12 and BIL-04 both link to the decision Reserve stock before payment.
Make every scenario checkable. Use numbers and names, such as 15 minutes and 2 units, instead of words like soon or some.

Drafting requirements with agents

Agents read requirements with get_requirement and draft new ones, changes to existing ones and retirements with propose_requirement, scenarios included. When a rule is still fuzzy, ask the agent for scenarios first: a handful of concrete cases is easier to review than a paragraph, and the statement usually follows from them.

Next steps

Proposals and reviews for how a proposed requirement gets approved.
Spec files in your repository for where requirement files land.
Decision log to record why a rule exists.