Specification Template (6 sections)
Summary — what this page covers The blank 6-section spec template used in the specification-first workflow (Day 1 Section 4). Copy the body below into
specs/<feature>.mdin your BookTracker clone and fill in each section. A completed worked example lives atspecs/reading-progress.mdin the BookTracker solution.
Keep a spec to roughly a page — you review the spec (cheap) instead of discovering misunderstandings
later in the code (expensive). Copy from the # [Feature name] heading down.
# [Feature name]
## 1. Context & scope
What problem does this solve and why now? State the goal in one or two sentences.
**In scope:** what this change includes.
**Out of scope:** what you are explicitly *not* doing (this is as important as what you are).
## 2. API contract
The endpoints this feature adds or changes. For each: method + route, request body/DTO,
and the response shapes with status codes (success and every error case).
## 3. Data model & persistence
Entities and fields touched. New or changed tables, columns, keys, indexes, and any migration
required. Note anything derived (computed, not stored).
## 4. Business rules
Validation, invariants, and state transitions the implementation must enforce — e.g. allowed value
ranges, required fields, and any state machine (which transitions are legal, which are no-ops).
## 5. Tests required
The concrete cases the implementation must satisfy. List the happy path plus the edge cases and
rejections that prove the rules in §4 hold.
## 6. Prohibitions & acceptance criteria
**Prohibitions:** explicit "do not"s — the mistakes you don't want made.
**Done when:** the definition of done (e.g. all §5 tests pass, endpoints honor §2, rules live in the
right layer).