--- id: AC-NNN # ticket ID, or DRAFT-NNN for pre-tracker title: status: draft # draft → accepted → shipped/superseded created: YYYY-MM-DD accepted: # filled when flipped to accepted shipped: # filled when flipped to shipped owner: ticket: AC-NNN # tracker ID; optional for repo-internal specs ticket-url: # optional, full URL related: [] --- # Spec AC-NNN: ## What What's being built. Concrete, specific. Show the thing, don't describe it. Works equally for features, refactors, and bug fixes. ## Why Why this work. Cite prior specs, constitution entries, or package SPEC.md if relevant. ## Decision <!-- Required before status: accepted. Stub OK while draft. --> We chose **<X>** over **<Y>**. ### Alternatives considered - **<X>** (chosen) — what it is, why it wins. - **<Y>** — what it is, why rejected. ### Rationale Why <X> wins, anchored on What and Why. ### Consequences - What becomes easier or possible. - What becomes harder or locked-in. - What we accept as the cost. <!-- Optional sections — add only when they add information. Apply the delete test: if a section would be filler, omit it. ## Concrete surface The files this delivers or changes. Often filled during iteration by analysis (scout) rather than at initial draft. ## Phased rollout For multi-phase work. Each phase: deliverables + acceptance criteria. Skip for single-pass changes. ## Open questions Unresolved choices. Include default-proposed answer where possible. Mark which phase resolves each. ## Non-goals Only when scope is genuinely ambiguous. "We won't boil the ocean" filler fails the delete test — skip it. ## Risks Real risks with mitigations. Synthetic "what if it breaks" risks fail the delete test — skip them. -->