SDD Spec Template

SDD Spec Template

The Markdown specification is the source of truth in Spec‑Driven Development. Code is generated from it; bugs are fixed by editing it first. Copy the template below into specs/<slice>.md.

---

Template

# Bounded Context: <Name>

> Status: <draft | active | deprecated>
> Owner: <operator>  ·  Context Entropy: <Low 1–3 | Medium 5–8 | High 13>

## Purpose
One paragraph: what this slice does and the business rule it serves.
Out of scope: what it explicitly does NOT do (prevents agent over-reach).

## Data model
For each entity: field — type — constraints — default.
  <entity>:
    id           uuid    pk
    <field>      <type>  <required? unique? range? fk?>   <default>
Relationships: <entity> 1—N <entity> (and the rule that governs it).

## API contract
For each endpoint: METHOD path → purpose
  - request shape (body / params)
  - success response (status + shape)
  - error responses (status + when)
  GET  /api/<resource>        → ...
  POST /api/<resource>        → 201 {..}; 400 when <rule>; 409 when <rule>

## UI / actions
Route(s) and what the user can do.
  /<route>:
    - <component / view>: <what it shows>
    - <action>: <trigger → result>, optimistic? yes/no
    - empty state / loading state / error state

## Edge cases  ← the most valuable section
Enumerate every boundary the agent must handle:
  - <invalid input> → <exact behaviour>
  - <auth/permission boundary> → <exact behaviour>
  - <concurrency / race> → <exact behaviour>
  - <external failure> → <fallback behaviour>

## Non-functional
  - AuthZ: who can do what
  - Performance: limits, pagination, rate limits
  - Data: retention, soft-delete vs hard-delete, PII handling

## Acceptance criteria
Checklist the Guardian verifies before this slice ships:
  - [ ] <observable behaviour 1>
  - [ ] <every edge case above has a passing test>

---

Writing rules

1. Specify behaviour, not implementation. Say what must be true, not how to code it — leave the how to the Engineer.
2. Edge cases are the spec. A spec without edge cases is a wish. Most generation defects trace to an unspecified boundary.
3. One bounded context per file. If a spec needs to describe two domains, split it — mirror Module 2's isolation rule.
4. The spec is versioned with the code. Commit specs/ alongside src/. A change to behaviour is a change to the spec, full stop.
5. Acceptance criteria are testable. If the Guardian can't turn a line into a test, rewrite it until it can.

Reality check. A spec is only the source of truth if you keep it that way. The single most common failure mode is hand‑patching code under deadline and never reflecting it back. When that happens, fix the spec the same day — a stale spec actively misleads both you and the agents.