spec.md in docs/markdown-object-model/ uses a document shape that Spec-Driven Development has since moved away from, so the first specification written under the standard no longer matches it.
Context and request
Current experience
The specification carries its acceptance criteria as a single consolidated gherkin block near the end of the document, containing every scenario for every requirement. That is what the specification template prescribed when the file was written, in PSModule/Markdown#33 on 2 August.
The standard now prescribes per-requirement #### Behavioral scenarios sections, with cross-cutting criteria labelled AC. Under the current convention, each requirement carries the scenarios that verify it, immediately beneath it.
The consolidated form has a practical cost that grows with the document. spec.md now holds twenty functional requirements, and a reader checking whether FR17 is verified has to scan a block of scenarios at the far end of the file and match them back by wording. Nothing links a scenario to the requirement it exercises, so a requirement can lose its coverage silently — which is the specific failure the current convention prevents.
Noticed while updating the same file for the merged section shape, in PSModule/Markdown#37. Restructuring was deliberately left out of that change: reorganising a document while rewriting its content makes both harder to review.
Desired experience
Each requirement carries its own behavioral scenarios, and criteria that span requirements are labelled and identifiable. A reader can tell at a glance whether a given requirement is verified.
Acceptance criteria
- Every functional requirement carries its scenarios beneath it, in
#### Behavioral scenarios form.
- Cross-cutting criteria are labelled
AC per the current standard.
- No scenario is lost in the move, and no requirement identifier changes — identifiers are append-only.
design.md and index.md still reference the specification correctly afterwards.
Related
The wider pattern is MSXOrg/docs#143: a normative structure changes in the standards repository, and the artifacts written under the previous version are not identified or updated. This is a second instance — the first was pull_request_template.md, where 96 of 96 repositories carried the pre-change structure.
Technical decisions
Restructure rather than rewrite. The scenarios are correct and were verified against the specification when written. Moving them under their requirements is a reorganisation, and any change to what a scenario asserts should be a separate, visible edit.
Not urgent, and not something to fold into a content change. The document is correct as it stands; it is a structural mismatch with the current standard, not a defect in what it says. Doing it on its own keeps the diff reviewable.
Implementation plan
spec.mdindocs/markdown-object-model/uses a document shape that Spec-Driven Development has since moved away from, so the first specification written under the standard no longer matches it.Context and request
Current experience
The specification carries its acceptance criteria as a single consolidated
gherkinblock near the end of the document, containing every scenario for every requirement. That is what the specification template prescribed when the file was written, in PSModule/Markdown#33 on 2 August.The standard now prescribes per-requirement
#### Behavioral scenariossections, with cross-cutting criteria labelledAC. Under the current convention, each requirement carries the scenarios that verify it, immediately beneath it.The consolidated form has a practical cost that grows with the document.
spec.mdnow holds twenty functional requirements, and a reader checking whether FR17 is verified has to scan a block of scenarios at the far end of the file and match them back by wording. Nothing links a scenario to the requirement it exercises, so a requirement can lose its coverage silently — which is the specific failure the current convention prevents.Noticed while updating the same file for the merged section shape, in PSModule/Markdown#37. Restructuring was deliberately left out of that change: reorganising a document while rewriting its content makes both harder to review.
Desired experience
Each requirement carries its own behavioral scenarios, and criteria that span requirements are labelled and identifiable. A reader can tell at a glance whether a given requirement is verified.
Acceptance criteria
#### Behavioral scenariosform.ACper the current standard.design.mdandindex.mdstill reference the specification correctly afterwards.Related
The wider pattern is MSXOrg/docs#143: a normative structure changes in the standards repository, and the artifacts written under the previous version are not identified or updated. This is a second instance — the first was
pull_request_template.md, where 96 of 96 repositories carried the pre-change structure.Technical decisions
Restructure rather than rewrite. The scenarios are correct and were verified against the specification when written. Moving them under their requirements is a reorganisation, and any change to what a scenario asserts should be a separate, visible edit.
Not urgent, and not something to fold into a content change. The document is correct as it stands; it is a structural mismatch with the current standard, not a defect in what it says. Doing it on its own keeps the diff reviewable.
Implementation plan
#### Behavioral scenariossection under the requirement it verifiesACper the standardmarkdownlint,textlint, andcodespellstay clean