docs/specs/TEMPLATE.md

# Spec NNNN - <feature name>

**Status:** draft | approved | implemented (+ deviations noted below)
**Phase:** 0 | 1 | 2 | 3    **Design doc ref:** §<n>

## Problem
One paragraph: what a researcher can't do today and why it matters.

## Contract
- Inputs (API/UI):
- Outputs (exact columns / fields / UI elements):
- Warnings & edge cases (UPPER_SNAKE codes, blocking vs warning):
- Metadata additions (bump output_schema_version? scoring changes?):

## Non-goals
What this spec deliberately does NOT cover.

## Tests
Named test cases that prove the contract (unit + integration + golden impact).

## Implementation notes
Files expected to change; smallest-diff approach; registry/library touchpoints.

## Deviations (filled after implementation)
-