Each requirement carries the Gherkin scenario that verifies it, so a spec maps every FR/NFR directly to its test instead of listing acceptance criteria in a separate section that a reader must cross-reference back to the requirements. Because every requirement then owns at least one Given/When/Then, every requirement is validatable by a test — each scenario becomes an executable acceptance test, giving requirement-level coverage and two-way traceability (every requirement has a test; every test traces to a requirement).
Context and request
Today Spec-Driven-Development.md defines requirements as ### FR1 — <statement> { #fr1 } headings and then collects the Given/When/Then behavior in a separate Acceptance criteria section. This splits a requirement from the test that proves it: the two drift, the mapping is implicit, and a reader has to match scenarios back to FR/NFR numbers by hand.
The change: a requirement and its verifying scenario live together. Each ### FRn/### NFRn heading owns its normative statement (MUST/SHOULD/MAY) followed by the gherkin Given/When/Then that defines what "satisfied" means for exactly that requirement. The standalone Acceptance criteria section is removed; the requirement is the test's home.
In scope: the spec-authoring convention and its template in Ways-of-Working/Spec-Driven-Development.md; any reference to acceptance criteria in Documentation-Model.md; and migrating existing capability specs to the co-located form. Out of scope: changing what a requirement means or the append-only anchor rules — only where the scenario lives.
Aggregate acceptance criteria: the convention documents one requirement-plus-scenario shape with no separate acceptance-criteria section; every FR/NFR in the convention's template carries its own Given/When/Then; and existing specs are migrated so each requirement owns its scenario, with no orphaned criteria block left behind.
Outcomes
- Every requirement is validatable by a test: its Gherkin scenario is the acceptance test, so requirement-level coverage is measurable — a requirement without a passing test is an unmet requirement.
- Two-way traceability: each test names the requirement it verifies via the stable anchor, and each requirement points at the behavior that proves it, so coverage gaps and orphaned tests are both visible.
- Drift is caught early: because the test sits with the requirement, changing one without the other is obvious in review.
Technical decisions
Keep the ### FRn — <statement> { #frn } heading, its stable append-only anchor, and the effect-not-mechanism rule; only move the Given/When/Then to sit under the requirement it verifies. A requirement MAY carry more than one scenario when it needs them; every requirement carries at least one, so "a requirement with no scenario" becomes an authoring error the reviewer catches — and, downstream, an untested requirement a test run can flag. The scenario names its requirement by anchor so tooling can map scenario to FR/NFR and report coverage. Update the spec template in the convention doc to show the new shape, and reconcile the Definition of Done reference that currently points at a separate acceptance-criteria section. Decompose migration per existing spec.
Implementation plan
Delivered through native sub-issues:
- Update
Spec-Driven-Development.md — replace the separate Acceptance criteria section with the per-requirement Gherkin convention and template, establish the requirement-to-test traceability rule, and fix the Documentation-Model/Definition-of-Done references.
- Migrate the deployment spec (
Capabilities/deployment/spec.md), whose scenarios are currently a separate block, to the co-located form as the reference example.
- Migrate the remaining capability specs to the co-located form.
Each requirement carries the Gherkin scenario that verifies it, so a spec maps every FR/NFR directly to its test instead of listing acceptance criteria in a separate section that a reader must cross-reference back to the requirements. Because every requirement then owns at least one Given/When/Then, every requirement is validatable by a test — each scenario becomes an executable acceptance test, giving requirement-level coverage and two-way traceability (every requirement has a test; every test traces to a requirement).
Context and request
Today Spec-Driven-Development.md defines requirements as
### FR1 — <statement> { #fr1 }headings and then collects the Given/When/Then behavior in a separate Acceptance criteria section. This splits a requirement from the test that proves it: the two drift, the mapping is implicit, and a reader has to match scenarios back toFR/NFRnumbers by hand.The change: a requirement and its verifying scenario live together. Each
### FRn/### NFRnheading owns its normative statement (MUST/SHOULD/MAY) followed by thegherkinGiven/When/Then that defines what "satisfied" means for exactly that requirement. The standalone Acceptance criteria section is removed; the requirement is the test's home.In scope: the spec-authoring convention and its template in
Ways-of-Working/Spec-Driven-Development.md; any reference to acceptance criteria in Documentation-Model.md; and migrating existing capability specs to the co-located form. Out of scope: changing what a requirement means or the append-only anchor rules — only where the scenario lives.Aggregate acceptance criteria: the convention documents one requirement-plus-scenario shape with no separate acceptance-criteria section; every FR/NFR in the convention's template carries its own Given/When/Then; and existing specs are migrated so each requirement owns its scenario, with no orphaned criteria block left behind.
Outcomes
Technical decisions
Keep the
### FRn — <statement> { #frn }heading, its stable append-only anchor, and the effect-not-mechanism rule; only move the Given/When/Then to sit under the requirement it verifies. A requirement MAY carry more than one scenario when it needs them; every requirement carries at least one, so "a requirement with no scenario" becomes an authoring error the reviewer catches — and, downstream, an untested requirement a test run can flag. The scenario names its requirement by anchor so tooling can map scenario toFR/NFRand report coverage. Update the spec template in the convention doc to show the new shape, and reconcile the Definition of Done reference that currently points at a separate acceptance-criteria section. Decompose migration per existing spec.Implementation plan
Delivered through native sub-issues:
Spec-Driven-Development.md— replace the separate Acceptance criteria section with the per-requirement Gherkin convention and template, establish the requirement-to-test traceability rule, and fix the Documentation-Model/Definition-of-Done references.Capabilities/deployment/spec.md), whose scenarios are currently a separate block, to the co-located form as the reference example.