Specification First

Core principle

We NEVER write code before the specification. This principle is fundamental for project quality.

Evidence & review: Every specification must list its source (source: meeting:<date>#<timestamp> or email:<message-id>) and must be manually reviewed by an architect/PM against the recording. AI agents can draft it, but nothing gets implemented without manual approval.

graph LR
    A[Requirements] --> B[Specification]
    B --> C{Review}
    C -->|Approved| D[Implementation]
    C -->|Changes| B
    D --> E[Validation]
    E --> F{Matches spec?}
    F -->|Yes| G[Deploy]
    F -->|No| D

Why Specification First?

Problem without a spec	Solution with a spec
Misunderstanding between analysts and developers	Single source of truth in spec.yaml
Scope creep	Changes must go through the proposal process
Inconsistent outputs	Validation against JSON Schema
Hard to test	Gherkin acceptance criteria
Hard to maintain	Documentation IS the specification

Section contents

Chapter	Description
Specification structure	Directory structure and spec types
spec.yaml format	Complete format of the spec file
Acceptance criteria	Gherkin format for QA
Validation and lifecycle	Validation rules and workflow

---

➡️ Continue to Specification structure.