ctx-spec — Write Docs an Agent Can Build From

The lifetime model and shared conventions live in ../ctx; this is the spec / ADR / design how-to layer.

How a spec is written — the writing standard

A spec is an authored doc an agent reads once and builds from. Four orthogonal axes govern every line; each governs a different thing, so they compose without clashing:

1. Status — normative vs informative. A spec states conclusions and constraints (normative). A note, example, or figure is never a requirement (informative). State a binding claim as a MUST/SHALL line — don't let a diagram imply it.
2. Strength — RFC 2119. MUST / SHOULD / MAY, all-caps, grep-able (all-caps only per RFC 8174). Lower-case "must" is prose, not a requirement.
3. Why-discipline (IRB) — which "why" may stay. Classify every "why" by what it does for the agent that reads the spec:
   • INTENT — a one-clause so-that that scopes a rule (X, so that Y) so the agent generalizes to cases the spec never enumerated. Stays inline with the rule.
   • RATIONALE — the justification of a choice among alternatives (chose X over Y because Z). Goes to an ADR (Considered options + Decision outcome), never the spec body.
   • BACKGROUND — context the model already knows, or history that changes no action. Cut it.
   • Delete-test: delete the clause — does an edge-case action change? Generalizes the rule → INTENT (keep). Only justifies a past choice → RATIONALE (→ ADR). Nothing → BACKGROUND (cut).
4. Granularity — specify the constraint, not the mechanism; testable (EARS), versioned. Its own section below (the most important one).

The one anti-pattern (mode bleed): a spec that teaches, compares options, or narrates what happened has let Explanation leak into a normative doc. Rationale → an ADR; comparison / review thinking → a report. The single "why" that belongs in a spec is INTENT — it carries normative force, because deleting it changes conformance at the edges.