# Spec-Driven Development

**Any coding project with multiple milestones MUST have specs before code.** Hard requirement, not a suggestion. Workflow: Plan → Spec → Test → Code.

At project start or when starting a new milestone, always read:
- `best-practices/spec-driven-development.md` — spec structure, requirement numbering, scenarios, maintenance
- `best-practices/test-driven-development.md` — edge case discovery, property-based testing, AI agent testing patterns

## Required artifacts

Every multi-milestone coding project must have:

1. **`SPEC.md`** — Index file at the project root. Lists all spec files with a "when to read" column. Same thin-index pattern as MEMORY.md.
2. **`spec/` directory** — One spec file per subsystem. Each spec follows: Overview, Responsibilities, Dependencies, Data Model, Requirements (numbered), Scenarios (given/when/then).
3. **Numbered requirements** — Each spec uses a prefix (e.g., `IG-1` for ingestion, `DB-1` for database). Requirements must be independently testable and unambiguous.
4. **Test files that reference spec IDs** — every test function name includes its requirement ID: `test_ig3_dedup_by_message_ts`.

## Workflow

1. **Plan** — architecture decisions, milestone breakdown, technology choices (PLAN.md)
2. **Spec** — detailed contracts, data models, interfaces, requirements, scenarios (spec/)
3. **Test** — write tests from the spec before code exists. They should all fail.
4. **Code** — implement until tests pass. Minimum code to satisfy the spec.
5. **Update** — if implementation reveals spec issues, update spec → test → code in that order.

## When to write specs

- **Before M1 implementation begins** — write specs for all subsystems in M1's scope
- **Before each subsequent milestone** — specs for new subsystems, updates to existing specs for changes
- **Spec changes and test changes ship in the same commit**
- **Code changes that affect interfaces require spec changes in the same commit**

## What does NOT need a spec

- Infrastructure-only projects (Helm values, Kustomize manifests, Ansible playbooks) — declarative, not behavioural
- Single-script utilities — a well-commented script with a test is sufficient
- Documentation-only changes