Specification Structure

A specification is complete when an implementer, human or agent, can build the change without inventing a decision. This contract lists the required sections, the id schemes that make behavior traceable, and the gates that decide whether the document is ready for implementation.

Scope note: this describes a product requirement specification written for a target project. It is not the convention for this repository's own change specs under docs/specs/.

Required Sections

Write these in order. Section 3 repeats once per delivery surface; every other section appears exactly once.

1. Requirement Overview — business background, in-scope and out-of-scope statements, affected roles, and a glossary for every domain term the rest of the document uses.
2. Data Model and Interface Contract — new and changed tables with column types and nullability, service contracts, public endpoints with request and response shapes, enumerations, and message or event payloads.
3. Surface Specification — for each delivery surface: the page or screen skeleton, component granularity, the state machine of each stateful view, and the action list with the permission that guards each action.
4. Business Rules — numbered BR-01, BR-02, ... Each rule is one testable statement that resolves to a single implementation site.
5. Exception Scenarios — numbered E-01, E-02, ... Each scenario names the trigger, the user-visible message on each affected surface, and the backend error code behind it.
6. Acceptance Criteria — numbered AC-01, AC-02, ... grouped by role. Each criterion is a Given / When / Then triple. Coverage spans normal, exception, and boundary cases.
7. Open Questions and Decision Record — unresolved items with an owner and a needed-by date, plus the decisions already taken with their rejected alternatives.

A two-surface project such as an admin console plus a mini-program instantiates section 3 twice and so reads as eight parts. That count belongs to the project, not to the contract. A single-surface service reads as seven parts, and a three-surface product reads as nine.

Id and Traceability Rules

• Ids are stable and append-only. When a rule dies, mark it withdrawn and keep the number; never renumber the list, because commits, tests, and review comments already cite the old ids.
• Every BR-* resolves to one implementation site. A rule that needs three unrelated code paths is really three rules.
• Every E-* maps the surfaced message to the error code that produces it, so the frontend text and the backend contract cannot drift apart silently.
• Every AC-* references the BR-* or E-* ids it exercises. Any rule or exception with no referencing criterion is unverified and blocks the gate below.
• Numbering is per specification, not global across the project.

Completeness Gates

Do not enter implementation while any gate fails:

• Term gate: every domain term used in a rule appears in the glossary.
• Contract gate: every field a surface displays or submits exists in section 2 with a type, and every enumerated value is listed.
• Rule gate: every BR-* is testable, meaning a reviewer can name the input that makes it pass and the input that makes it fail.
• Exception gate: every failure path a rule implies has an E-* entry. Silent failure is a specification defect, not an implementation detail.
• Coverage gate: every BR-* and E-* is referenced by at least one AC-*, and the criteria include at least one boundary case.
• Decision gate: no open question blocks a rule that is in scope for this iteration. Move the blocked rule out of scope or resolve the question.

Mark anything still undecided explicitly rather than guessing. An unresolved marker is a legitimate specification state; a plausible invented value is not.

Anti-Patterns

• Prose without ids. Paragraphs describing behavior cannot be cited by a test, a commit, or a review comment.
• Screenshot as spec. An image fixes a layout but states no rule, no state transition, and no permission.
• Happy path only. Sections 5 and 6 carry most of the implementation risk; omitting them moves the cost into debugging.
• Restating the schema as the rule. A column type is a contract, not a business rule. BR-* states what the system must decide, not what it stores.
• Copying a section from another project. Reuse the section list; rewrite the content against observed facts about this target.
• Deferring acceptance to review time. Criteria written after the code exists describe the implementation instead of constraining it.

Read Next

• Use examples/README.md to calibrate a concrete section against a comparable stack.
• Use the Bootstrap domain index for the boundaries of this domain and the routes onward to verification design, instruction owners, and repeated-work owners.