lite-sdd-specify

Write or update a spec.md — the functional source of truth the implementation is planned against and kept in sync with. One spec.md lives in each feature folder (specs/NNN-feature-name/spec.md); for the folder and numbering rules see lite-sdd-overview → ## Repository layout.

A spec is functional, concise, and exhaustive — see the global principles in lite-sdd-overview. It must be short enough that a human validates it quickly and precise enough that an agent builds from it without guessing.

Structure of a spec.md

# NNN — <Feature title>

## Scope

One short paragraph: what this feature covers and what it explicitly does not
(point to the sibling features that own the rest).

---

## US-NNN-01 — <User story title>

**As a** <role>, **I want** <capability>, **so that** <outcome>.

### Behaviour

The business rules, stated tightly. Use tables for branching rules, diagrams
for flows or layouts. Every rule the implementation must honour appears here.

### Acceptance criteria

- [ ] One checkable statement per rule
- [ ] …

### Edge cases

| Case | Expected behaviour |
|---|---|
| … | … |

---

## US-NNN-02 — …

Rules

• One major paragraph (US) per user story. Each US is self-contained: its business rules, acceptance criteria, and edge cases all live under it.
• State everything, briefly. A US carries all the rules, criteria, and edge cases for its scope — but in the fewest words possible. Reach for a table or a diagram before a paragraph.
• Stay functional. Describe behaviour, not implementation. Keep platform and runtime vocabulary out of feature specs.
• Cross-reference, don't duplicate. When another feature owns part of the behaviour, name it (e.g. "the filters are specified in feature 203") instead of restating it.

Keep the specs/README.md index in sync

specs/README.md is the project's table of contents (owned by lite-sdd-overview → ### The specs/README.md index). Every time you write or update a spec.md, update the index in the same pass so navigation never drifts from the specs:

• New feature folder → add its node under the right *00 block, in numeric order.
• New, renamed, or removed user story → add, rename, or remove its US-NNN-NN line under the feature, and check the heading anchor the link points to still resolves (## US-NNN-01 — Creation → #us-nnn-01--creation).
• New *00 block → add its level-0 node (and its ## NNN — <App> section).

The index is links only — titles and US numbers, never behaviour. The rules themselves stay in the spec.md files.

The spec reflects the desired state, not the history

A spec evolves over time — a new US, a changed behaviour, a rule pinned down after a bug. It always describes the state you want now, not how it got there. When a behaviour changes, rewrite the affected part: do not keep the old version, changelogs, "previously…" notes, or struck-through rules in the spec. Version history lives in git, not in spec.md.

No functional grey zones

A finished spec leaves no functional ambiguity. Whenever you detect an edge case, an unspecified behaviour, or any open question about how the feature should work functionally, ask the user — never guess, never quietly pick a default, never defer the decision to implementation time. Fold every answer back into the spec so the next reader (human or agent) finds the rule already written down. Keep raising questions until there is nothing functional left undecided.

The *00 application-level spec

The *00 spec of a block (100, 200, …) is not structured in user stories. The user-story layout above applies to feature specs (N01+); a *00 uses descriptive sections instead. US may be completely absent — that is expected, not a gap. For what a *00 is and why it may carry technical vocabulary, see lite-sdd-overview → ## The *00 application-level spec.

A *00 contains:

• Scope — what the app covers and what is explicitly out of scope.
• Platform / runtime / data source — the one spec allowed to name technical vocabulary (target platform, runtime, where data comes from).
• Cross-cutting rules — rules shared by every feature in the block.
• Shared layout — header, footer, navigation, responsive frame.
• Feature index — NNN → topic routing for the block, with cross-references.

A *00 does not contain concrete user stories or detailed screens/flows — those live in the N01+ feature specs, which refer back to the *00 for shared rules.

# N00 — <App name>

## Scope

## Platform / runtime / data source

## Cross-cutting rules

## <Shared layout: header / footer / navigation / …>

## Feature index

The happy-path only and one US per story anti-patterns below do not apply to a *00 — it need not have any US.

Anti-patterns (DO NOT DO)

Anti-pattern	Correct approach
Implementation detail in a feature spec	Keep it functional; technical context belongs in the *00 spec
Long prose that hides the rules	Tighten to the essential; use tables and diagrams
Happy-path only	Every US states its business rules, acceptance criteria and edge cases
Repeating behaviour owned by another feature	Reference the feature number and move on
One giant US covering several stories	One US per story, each self-contained
Over-splitting a *00 into fake user stories	Use descriptive sections; a *00 need not have any US
Guessing or defaulting an unspecified behaviour / edge case	Ask the user, then write the answer into the spec
Keeping the old behaviour, changelog, or "previously…" notes when a rule changes	Rewrite to the desired state; history lives in git
Adding or renaming a US without touching specs/README.md	Update the index in the same pass; keep US links and anchors current

Skill boundaries

• Project layout, numbering, and skill routing → lite-sdd-overview
• New project setup → lite-sdd-init
• Planning and syncing the implementation → lite-sdd-implement