feat(workflows): add spec-create, the author leg of the spec trio

spec-create is the front of the spec-create → spec-review → spec-response trio: the author writes a short design spec before non-trivial code, shaped to pass spec-review's readiness gate. It runs a when-to-spec proportionality gate first, then problem-first framing, design with forced alternatives and inline mini-ADR decisions, implementation phases with acceptance criteria and a readiness-dimensions menu, a terseness pass, and a hand-off self-check against the review rubric.

4 files changed, 398 insertions, 0 deletions

diff --git a/.ai/workflows/INDEX.org b/.ai/workflows/INDEX.org
index 157a4e7..9b957d2 100644
--- a/.ai/workflows/INDEX.org
+++ b/.ai/workflows/INDEX.org
@@ -73,6 +73,8 @@ This index must list every =.org= file in =.ai/workflows/= except this one and e
 
 ** Specs and design
 
+- =spec-create.org= — author a design/feature spec before non-trivial work (more than ~6 hours, or real trade-offs): a when-to-spec gate, then problem-first framing, design + alternatives + inline mini-ADR decisions, implementation phases + acceptance criteria + a readiness-dimensions menu, a terseness pass, and a hand-off self-check against the review rubric. The *author* side that starts the trio; its output feeds =spec-review.org=.
+  - Triggers: "let's write a spec", "spec this out", "create a spec for X", "spec-create workflow"
 - =spec-review.org= — review a design/feature spec for implementation-readiness: run the readiness gate, read the code first, evaluate across dimensions, assign a rubric (Ready / Ready-with-caveats / Not-ready / Needs-research), and write a =<spec>-review.org= file when not ready. The *reviewer* side; its output feeds =spec-response.org=.
   - Triggers: "review the spec", "is this spec implementation-ready?", "spec-review workflow", "review the design"
 - =spec-response.org= — fold an external spec review back in: decide accept / modify / reject for every recommendation, weave accepts into the spec body, document modifies and rejects in a "Review dispositions" section, reconcile cross-spec tensions, iterate to implementation-ready. The *author* side; consumes the =<spec>-review.org= file =spec-review.org= produces.
diff --git a/.ai/workflows/spec-create.org b/.ai/workflows/spec-create.org
new file mode 100644
index 0000000..42f36b9
--- /dev/null
+++ b/.ai/workflows/spec-create.org
@@ -0,0 +1,197 @@
+#+TITLE: Spec-Create Workflow
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-06-09
+
+* Overview
+
+This workflow produces a *spec* — a short design document written before non-trivial code, whose real product is the thinking it forces, not the artifact. A spec exists to solve a problem on paper, where iterating costs minutes, before solving it in code, where iterating costs days.
+
+The guiding principle, drawn from how Google, Oxide, Amazon, Basecamp, and the ADR tradition actually write these: /the most important person to convince is the author/. If the design looks weak on the page, the code will be worse. Writing the spec *is* the design work.
+
+It is the front of a trio:
+- =spec-create.org= (this one) — author writes the spec.
+- =spec-review.org= — a reviewer gates the spec for implementation-readiness and writes =<spec-basename>-review.org=.
+- =spec-response.org= — the author folds the review back in.
+
+The spec this workflow produces has to *pass spec-review's gate* — that gate is the definition of done. So the structure below is built to answer the reviewer's questions up front. Keep it lightweight anyway: a short required spine plus a *readiness-dimensions menu* where each item is either answered or explicitly marked "N/A because…". The best spec is the shortest one that still lets an engineer build it, test it, and ship behavior that matches the user's mental model.
+
+* When to Use This Workflow
+
+Trigger phrases: "let's write a spec", "spec this out", "create a spec for X", "I want a spec-create workflow" (meta — that creates/edits this file; see protocols.org terminology).
+
+** Phase 0 — The when-to-spec gate (do this first, bail cheaply)
+
+A spec is overhead. Only write one when the work clears the proportionality bar. Write a spec when *two or more* hold:
+
+- More than 6 hours of work.
+- The design is uncertain, ambiguous, or contentious.
+- There are *real trade-offs* — more than one viable approach with different consequences. (Malte Ubl's test: if there are no trade-offs to weigh, skip the spec and write the code.)
+- The change is cross-cutting or hard to reverse later.
+
+If the bar isn't met, say so and stop: "this is below the spec bar — just do it." Don't spec a one-liner; the writing cost would exceed the thinking benefit.
+
+* The Workflow
+
+Mark anything unknown as an open decision rather than stalling on it.
+
+** Phase 1 — Frame the problem (problem first, always)
+
+Before any design, write the problem from the *caller's or user's* point of view. A concrete problem story is the baseline every later design decision is judged against.
+
+Capture, in this order:
+1. *Summary* — 2-3 sentences a reader can triage in 30 seconds: what this is and why it exists.
+2. *Problem / Context* — the actual problem, concretely. What's wrong now, what forces are at play.
+3. *Goals and Non-Goals* — bullets. The *non-goals do most of the scoping work* — state plainly what this will not do. If you can't articulate the boundary, you're not ready to design.
+4. *Scope tiers* — separate what's in v1 from what's out-of-scope and what's deferred to vNext. The reviewer gates on this separation; vNext items get logged to =todo.org= at hand-off (Phase 6).
+
+** Phase 2 — Design, alternatives, decisions
+
+1. *Design* — overview first, then detail. Write the reasoning as *prose, not bullet dumps* — prose exposes weak logic that bullets let you hide. Use bullets only for genuinely enumerable lists. When the thing has an interface, use the *two-altitude* split (Rust RFC): explain it once for a user/caller, once for an implementer.
+2. *Alternatives considered* — the load-bearing section authors skip and reviewers need most. For each option, force a why-not with the MADR grammar: "Good, because… / Bad, because… / Neutral, because…". Even one rejected option, with the reason, beats presenting one path as inevitable.
+3. *Decisions* — capture each real choice as an inline mini-ADR (Nygard's spine):
+   - =State:= proposed | accepted | superseded
+   - =Context:= the forces motivating the choice
+   - =Decision:= the call, stated actively ("We will…")
+   - =Consequences:= what gets easier *and* what gets harder (both halves — a decision with only upsides is under-examined)
+   An *open* decision is simply =State: proposed= plus an *owner* and a *by-when*; resolving it flips to =accepted= with the rationale in Decision. Never rewrite a resolved decision — mark it =superseded= and keep the old one. Keep decisions inline here; promote to a standalone numbered ADR only when a decision outlives or spans beyond this one spec. (The decision =State= is distinct from the spec-wide =Status= in the metadata header.)
+
+** Phase 3 — Make it buildable
+
+This is where the spec earns a "Ready" from review: an engineer must be able to build it in steps, know when it's done, and never have to invent product behavior mid-implementation.
+
+1. *Implementation phases* — decompose the work into phases each small enough to finish in one focused session and each leaving the tree in a working (not half-broken) state. =spec-review= lifts this section straight into =todo.org= tasks, so a spec that can't be phased fails the gate — the absence is itself a finding.
+2. *Acceptance criteria* — the observable conditions that mean the feature works, written as checkable items. The review's test-surface task mirrors these.
+3. *Readiness dimensions* — walk this menu and, for each, either define the behavior or write "N/A because…". The escape hatch keeps a simple spec short; the prompt keeps a hidden decision from slipping into implementation:
+   - *Data model & ownership* — what's user-authored / generated / cached / remote; who owns each editable region; what persists vs refreshes.
+   - *Errors, empty states & failure* — actionable messages naming the operation, object, and next step; partial-failure and conflict behavior; no silent data loss.
+   - *Security & privacy* — credentials, sensitive data, redaction in logs.
+   - *Observability* — how the user/operator sees progress and failures and isolates a problem from a bug report; long-op progress/cancel.
+   - *Performance & scale* — expected counts, likely bottlenecks, long-running ops tested with fakes rather than flaky live dependencies.
+   - *Reuse & lost opportunities* — what the platform/framework already provides; preserved, wrapped, or intentionally replaced.
+   - *Architecture fit* — named integration points; weak points and their mitigations (concurrency, lifecycle, failure isolation).
+   - *Config surface* — public knobs named, with defaults and safety notes.
+   - *Documentation plan* — README / user / developer / migration docs, or why none are needed.
+   - *Dev tooling* — Makefile/script targets for setup, test, lint, coverage, cleanup, slow/manual verification.
+   - *Rollout, compatibility & rollback* — migration, opt-out/revert, and dry-run/backup for anything that changes persisted data, public APIs, or external/shared state.
+   - *External APIs & deps* — assumed fields/mutations/enums verified against current schema/docs/live responses, or listed as research prerequisites.
+
+** Phase 4 — Risks and the terseness pass
+
+1. *Risks, rabbit holes, and drawbacks* — name the known technical unknowns and how you'll dodge them (Shape Up's rabbit holes), plus the costs of the chosen path.
+2. *Cut it.* "Remove every word that can be removed" — expect a ~30% cut from the first draft with no information loss. Push heavy detail, data, and long calculations to an appendix so the core argument stays readable in one sitting. Tone is conversational and human, not formal — walls of text go unread. Run =/voice general= (or =/voice prose= if it's prose-heavy) for this pass.
+
+** Phase 5 — Wire it up (conventions)
+
+- *Filename + location:* =docs/<problem-slug>-spec.org=. Org-mode. The slug names the *problem/feature*, not a date. Must end in =-spec.org=.
+- *Metadata header:* a small table at the top — Status, Owner, Reviewer(s), Date, Related (link to the task/ticket).
+- *Review-and-iteration-history stub:* add a =Review and iteration history= section at the bottom and seed it with the author's first entry. =spec-review= and =spec-response= append provenance entries here, so the heading shape is a contract: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role=, body fields What / Why / Artifacts.
+- *Cross-link both ways:* the spec links its task; the task links the spec (replace the task's inline plan with a terse description + a =file:= link to the spec).
+
+** Phase 6 — Hand-off readiness
+
+Self-assess against =spec-review='s rubric before handing off, so the review starts from a clean spec instead of catching basics:
+- *Decisions:* no =State: proposed= decisions remain, or the author *consciously accepts* the risk of building with one open (recorded).
+- *APIs:* every external API assumption is verified or listed as a research prerequisite — otherwise the honest verdict is =Needs research=.
+- *Self-rubric:* Ready / Ready with caveats / Not ready / Needs research. If it isn't at least =Ready with caveats=, keep drafting.
+- *Defer:* log open decisions and vNext items to =todo.org= (v1 work =[#B]=, vNext/someday =[#D]=) — don't leave them only in the spec.
+
+Then it's ready for =spec-review.org=. Snapshot-vs-living rule: keep the spec living for small in-flight corrections; on a *material* design pivot, write a new =-spec.org= referencing the old rather than letting one doc accrete contradictions. The drift to avoid is the code silently becoming the only real spec.
+
+* The Template
+
+#+begin_src org
+,#+TITLE: <Feature> — Spec
+,#+AUTHOR: <author>
+,#+DATE: <YYYY-MM-DD>
+
+,* Metadata
+| Status   | draft                       |
+| Owner    | <name>                      |
+| Reviewer | <name(s)>                   |
+| Related  | [[file:...][task / ticket]] |
+
+,* Summary
+<2-3 sentences: what this is and why it exists.>
+
+,* Problem / Context
+<The problem from the caller's/user's view. What's wrong now; what forces apply.>
+
+,* Goals and Non-Goals
+,** Goals
+- <goal>
+,** Non-Goals
+- <what this deliberately will not do>
+,** Scope tiers
+- v1: <in scope now>
+- Out of scope: <won't do>
+- vNext: <deferred — log to todo.org>
+
+,* Design
+<Overview first, then detail. Prose for reasoning. Two-altitude if there's an interface.>
+
+,* Alternatives Considered
+,** <Option A>
+- Good, because <…>
+- Bad, because <…>
+- Neutral, because <…>
+
+,* Decisions
+,** <Decision name>
+- State: proposed | accepted | superseded
+- Owner / by-when: <name> / <when>   (open decisions only)
+- Context: <forces>
+- Decision: We will <…>
+- Consequences: easier <…>; harder <…>
+
+,* Implementation phases
+,** Phase 1 — <smallest noun phrase>
+<what this phase delivers; leaves the tree working.>
+
+,* Acceptance criteria
+- [ ] <observable, checkable condition>
+
+,* Readiness dimensions
+Answer each, or write "N/A because…".
+- Data model & ownership: <…>
+- Errors, empty states & failure: <…>
+- Security & privacy: <…>
+- Observability: <…>
+- Performance & scale: <…>
+- Reuse & lost opportunities: <…>
+- Architecture fit & weak points: <…>
+- Config surface: <…>
+- Documentation plan: <…>
+- Dev tooling: <…>
+- Rollout, compatibility & rollback: <…>
+- External APIs & deps: <verified / prerequisite>
+
+,* Risks, Rabbit Holes, and Drawbacks       (optional)
+- <known unknown + how you'll dodge it>
+
+,* Testing / Verification / Rollout          (optional)
+<How it's verified; staged rollout or migration if any.>
+
+,* References / Appendix                      (optional)
+<Links, supporting data, heavy diagrams.>
+
+,* Review and iteration history
+,** <YYYY-MM-DD Day @ HH:MM:SS -ZZZZ> — <Contributor> — author
+- What: initial draft.
+- Why: <decision pressure>.
+- Artifacts: <links, task id>.
+#+end_src
+
+The required spine runs Summary through Readiness dimensions, plus the Review-and-iteration-history stub. Sections marked =(optional)= are include-only-if-needed; inside Readiness dimensions, "N/A because…" is a valid answer for any item the design doesn't touch.
+
+* Common Mistakes
+
+1. *Speccing trivial work.* Phase 0 exists to stop this. No trade-offs → write the code.
+2. *Solution before problem.* If the reader doesn't understand the problem first, the design can't be judged. Problem leads, always.
+3. *Skipping Alternatives + Decisions.* These are the sections that carry the spec's value. A single inevitable path with no why-nots is a red flag.
+4. *Listing only the upside of a decision.* Record what gets harder too.
+5. *Polishing before drafting.* Get the skeleton down rough; rigor comes in revision. Don't stall on an unknown — file it as an open decision.
+6. *Letting it sprawl.* Skip the terseness pass and the spec goes unread. Cut ~30%; appendix the rest.
+7. *No owner, no status.* A spec nobody owns drifts; a spec with no status can't be triaged.
+8. *Editing a resolved decision in place.* Supersede, don't overwrite — the history is the value.
+9. *No implementation phases.* =spec-review= can't decompose the work into tasks and the spec fails the gate. Phase it, each step leaving a working tree.
+10. *Silently skipping a readiness dimension.* Each is answered or explicitly "N/A because…" — an unanswered dimension is a hidden decision the implementer inherits.
diff --git a/claude-templates/.ai/workflows/INDEX.org b/claude-templates/.ai/workflows/INDEX.org
index 157a4e7..9b957d2 100644
--- a/claude-templates/.ai/workflows/INDEX.org
+++ b/claude-templates/.ai/workflows/INDEX.org
@@ -73,6 +73,8 @@ This index must list every =.org= file in =.ai/workflows/= except this one and e
 
 ** Specs and design
 
+- =spec-create.org= — author a design/feature spec before non-trivial work (more than ~6 hours, or real trade-offs): a when-to-spec gate, then problem-first framing, design + alternatives + inline mini-ADR decisions, implementation phases + acceptance criteria + a readiness-dimensions menu, a terseness pass, and a hand-off self-check against the review rubric. The *author* side that starts the trio; its output feeds =spec-review.org=.
+  - Triggers: "let's write a spec", "spec this out", "create a spec for X", "spec-create workflow"
 - =spec-review.org= — review a design/feature spec for implementation-readiness: run the readiness gate, read the code first, evaluate across dimensions, assign a rubric (Ready / Ready-with-caveats / Not-ready / Needs-research), and write a =<spec>-review.org= file when not ready. The *reviewer* side; its output feeds =spec-response.org=.
   - Triggers: "review the spec", "is this spec implementation-ready?", "spec-review workflow", "review the design"
 - =spec-response.org= — fold an external spec review back in: decide accept / modify / reject for every recommendation, weave accepts into the spec body, document modifies and rejects in a "Review dispositions" section, reconcile cross-spec tensions, iterate to implementation-ready. The *author* side; consumes the =<spec>-review.org= file =spec-review.org= produces.
diff --git a/claude-templates/.ai/workflows/spec-create.org b/claude-templates/.ai/workflows/spec-create.org
new file mode 100644
index 0000000..42f36b9
--- /dev/null
+++ b/claude-templates/.ai/workflows/spec-create.org
@@ -0,0 +1,197 @@
+#+TITLE: Spec-Create Workflow
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-06-09
+
+* Overview
+
+This workflow produces a *spec* — a short design document written before non-trivial code, whose real product is the thinking it forces, not the artifact. A spec exists to solve a problem on paper, where iterating costs minutes, before solving it in code, where iterating costs days.
+
+The guiding principle, drawn from how Google, Oxide, Amazon, Basecamp, and the ADR tradition actually write these: /the most important person to convince is the author/. If the design looks weak on the page, the code will be worse. Writing the spec *is* the design work.
+
+It is the front of a trio:
+- =spec-create.org= (this one) — author writes the spec.
+- =spec-review.org= — a reviewer gates the spec for implementation-readiness and writes =<spec-basename>-review.org=.
+- =spec-response.org= — the author folds the review back in.
+
+The spec this workflow produces has to *pass spec-review's gate* — that gate is the definition of done. So the structure below is built to answer the reviewer's questions up front. Keep it lightweight anyway: a short required spine plus a *readiness-dimensions menu* where each item is either answered or explicitly marked "N/A because…". The best spec is the shortest one that still lets an engineer build it, test it, and ship behavior that matches the user's mental model.
+
+* When to Use This Workflow
+
+Trigger phrases: "let's write a spec", "spec this out", "create a spec for X", "I want a spec-create workflow" (meta — that creates/edits this file; see protocols.org terminology).
+
+** Phase 0 — The when-to-spec gate (do this first, bail cheaply)
+
+A spec is overhead. Only write one when the work clears the proportionality bar. Write a spec when *two or more* hold:
+
+- More than 6 hours of work.
+- The design is uncertain, ambiguous, or contentious.
+- There are *real trade-offs* — more than one viable approach with different consequences. (Malte Ubl's test: if there are no trade-offs to weigh, skip the spec and write the code.)
+- The change is cross-cutting or hard to reverse later.
+
+If the bar isn't met, say so and stop: "this is below the spec bar — just do it." Don't spec a one-liner; the writing cost would exceed the thinking benefit.
+
+* The Workflow
+
+Mark anything unknown as an open decision rather than stalling on it.
+
+** Phase 1 — Frame the problem (problem first, always)
+
+Before any design, write the problem from the *caller's or user's* point of view. A concrete problem story is the baseline every later design decision is judged against.
+
+Capture, in this order:
+1. *Summary* — 2-3 sentences a reader can triage in 30 seconds: what this is and why it exists.
+2. *Problem / Context* — the actual problem, concretely. What's wrong now, what forces are at play.
+3. *Goals and Non-Goals* — bullets. The *non-goals do most of the scoping work* — state plainly what this will not do. If you can't articulate the boundary, you're not ready to design.
+4. *Scope tiers* — separate what's in v1 from what's out-of-scope and what's deferred to vNext. The reviewer gates on this separation; vNext items get logged to =todo.org= at hand-off (Phase 6).
+
+** Phase 2 — Design, alternatives, decisions
+
+1. *Design* — overview first, then detail. Write the reasoning as *prose, not bullet dumps* — prose exposes weak logic that bullets let you hide. Use bullets only for genuinely enumerable lists. When the thing has an interface, use the *two-altitude* split (Rust RFC): explain it once for a user/caller, once for an implementer.
+2. *Alternatives considered* — the load-bearing section authors skip and reviewers need most. For each option, force a why-not with the MADR grammar: "Good, because… / Bad, because… / Neutral, because…". Even one rejected option, with the reason, beats presenting one path as inevitable.
+3. *Decisions* — capture each real choice as an inline mini-ADR (Nygard's spine):
+   - =State:= proposed | accepted | superseded
+   - =Context:= the forces motivating the choice
+   - =Decision:= the call, stated actively ("We will…")
+   - =Consequences:= what gets easier *and* what gets harder (both halves — a decision with only upsides is under-examined)
+   An *open* decision is simply =State: proposed= plus an *owner* and a *by-when*; resolving it flips to =accepted= with the rationale in Decision. Never rewrite a resolved decision — mark it =superseded= and keep the old one. Keep decisions inline here; promote to a standalone numbered ADR only when a decision outlives or spans beyond this one spec. (The decision =State= is distinct from the spec-wide =Status= in the metadata header.)
+
+** Phase 3 — Make it buildable
+
+This is where the spec earns a "Ready" from review: an engineer must be able to build it in steps, know when it's done, and never have to invent product behavior mid-implementation.
+
+1. *Implementation phases* — decompose the work into phases each small enough to finish in one focused session and each leaving the tree in a working (not half-broken) state. =spec-review= lifts this section straight into =todo.org= tasks, so a spec that can't be phased fails the gate — the absence is itself a finding.
+2. *Acceptance criteria* — the observable conditions that mean the feature works, written as checkable items. The review's test-surface task mirrors these.
+3. *Readiness dimensions* — walk this menu and, for each, either define the behavior or write "N/A because…". The escape hatch keeps a simple spec short; the prompt keeps a hidden decision from slipping into implementation:
+   - *Data model & ownership* — what's user-authored / generated / cached / remote; who owns each editable region; what persists vs refreshes.
+   - *Errors, empty states & failure* — actionable messages naming the operation, object, and next step; partial-failure and conflict behavior; no silent data loss.
+   - *Security & privacy* — credentials, sensitive data, redaction in logs.
+   - *Observability* — how the user/operator sees progress and failures and isolates a problem from a bug report; long-op progress/cancel.
+   - *Performance & scale* — expected counts, likely bottlenecks, long-running ops tested with fakes rather than flaky live dependencies.
+   - *Reuse & lost opportunities* — what the platform/framework already provides; preserved, wrapped, or intentionally replaced.
+   - *Architecture fit* — named integration points; weak points and their mitigations (concurrency, lifecycle, failure isolation).
+   - *Config surface* — public knobs named, with defaults and safety notes.
+   - *Documentation plan* — README / user / developer / migration docs, or why none are needed.
+   - *Dev tooling* — Makefile/script targets for setup, test, lint, coverage, cleanup, slow/manual verification.
+   - *Rollout, compatibility & rollback* — migration, opt-out/revert, and dry-run/backup for anything that changes persisted data, public APIs, or external/shared state.
+   - *External APIs & deps* — assumed fields/mutations/enums verified against current schema/docs/live responses, or listed as research prerequisites.
+
+** Phase 4 — Risks and the terseness pass
+
+1. *Risks, rabbit holes, and drawbacks* — name the known technical unknowns and how you'll dodge them (Shape Up's rabbit holes), plus the costs of the chosen path.
+2. *Cut it.* "Remove every word that can be removed" — expect a ~30% cut from the first draft with no information loss. Push heavy detail, data, and long calculations to an appendix so the core argument stays readable in one sitting. Tone is conversational and human, not formal — walls of text go unread. Run =/voice general= (or =/voice prose= if it's prose-heavy) for this pass.
+
+** Phase 5 — Wire it up (conventions)
+
+- *Filename + location:* =docs/<problem-slug>-spec.org=. Org-mode. The slug names the *problem/feature*, not a date. Must end in =-spec.org=.
+- *Metadata header:* a small table at the top — Status, Owner, Reviewer(s), Date, Related (link to the task/ticket).
+- *Review-and-iteration-history stub:* add a =Review and iteration history= section at the bottom and seed it with the author's first entry. =spec-review= and =spec-response= append provenance entries here, so the heading shape is a contract: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role=, body fields What / Why / Artifacts.
+- *Cross-link both ways:* the spec links its task; the task links the spec (replace the task's inline plan with a terse description + a =file:= link to the spec).
+
+** Phase 6 — Hand-off readiness
+
+Self-assess against =spec-review='s rubric before handing off, so the review starts from a clean spec instead of catching basics:
+- *Decisions:* no =State: proposed= decisions remain, or the author *consciously accepts* the risk of building with one open (recorded).
+- *APIs:* every external API assumption is verified or listed as a research prerequisite — otherwise the honest verdict is =Needs research=.
+- *Self-rubric:* Ready / Ready with caveats / Not ready / Needs research. If it isn't at least =Ready with caveats=, keep drafting.
+- *Defer:* log open decisions and vNext items to =todo.org= (v1 work =[#B]=, vNext/someday =[#D]=) — don't leave them only in the spec.
+
+Then it's ready for =spec-review.org=. Snapshot-vs-living rule: keep the spec living for small in-flight corrections; on a *material* design pivot, write a new =-spec.org= referencing the old rather than letting one doc accrete contradictions. The drift to avoid is the code silently becoming the only real spec.
+
+* The Template
+
+#+begin_src org
+,#+TITLE: <Feature> — Spec
+,#+AUTHOR: <author>
+,#+DATE: <YYYY-MM-DD>
+
+,* Metadata
+| Status   | draft                       |
+| Owner    | <name>                      |
+| Reviewer | <name(s)>                   |
+| Related  | [[file:...][task / ticket]] |
+
+,* Summary
+<2-3 sentences: what this is and why it exists.>
+
+,* Problem / Context
+<The problem from the caller's/user's view. What's wrong now; what forces apply.>
+
+,* Goals and Non-Goals
+,** Goals
+- <goal>
+,** Non-Goals
+- <what this deliberately will not do>
+,** Scope tiers
+- v1: <in scope now>
+- Out of scope: <won't do>
+- vNext: <deferred — log to todo.org>
+
+,* Design
+<Overview first, then detail. Prose for reasoning. Two-altitude if there's an interface.>
+
+,* Alternatives Considered
+,** <Option A>
+- Good, because <…>
+- Bad, because <…>
+- Neutral, because <…>
+
+,* Decisions
+,** <Decision name>
+- State: proposed | accepted | superseded
+- Owner / by-when: <name> / <when>   (open decisions only)
+- Context: <forces>
+- Decision: We will <…>
+- Consequences: easier <…>; harder <…>
+
+,* Implementation phases
+,** Phase 1 — <smallest noun phrase>
+<what this phase delivers; leaves the tree working.>
+
+,* Acceptance criteria
+- [ ] <observable, checkable condition>
+
+,* Readiness dimensions
+Answer each, or write "N/A because…".
+- Data model & ownership: <…>
+- Errors, empty states & failure: <…>
+- Security & privacy: <…>
+- Observability: <…>
+- Performance & scale: <…>
+- Reuse & lost opportunities: <…>
+- Architecture fit & weak points: <…>
+- Config surface: <…>
+- Documentation plan: <…>
+- Dev tooling: <…>
+- Rollout, compatibility & rollback: <…>
+- External APIs & deps: <verified / prerequisite>
+
+,* Risks, Rabbit Holes, and Drawbacks       (optional)
+- <known unknown + how you'll dodge it>
+
+,* Testing / Verification / Rollout          (optional)
+<How it's verified; staged rollout or migration if any.>
+
+,* References / Appendix                      (optional)
+<Links, supporting data, heavy diagrams.>
+
+,* Review and iteration history
+,** <YYYY-MM-DD Day @ HH:MM:SS -ZZZZ> — <Contributor> — author
+- What: initial draft.
+- Why: <decision pressure>.
+- Artifacts: <links, task id>.
+#+end_src
+
+The required spine runs Summary through Readiness dimensions, plus the Review-and-iteration-history stub. Sections marked =(optional)= are include-only-if-needed; inside Readiness dimensions, "N/A because…" is a valid answer for any item the design doesn't touch.
+
+* Common Mistakes
+
+1. *Speccing trivial work.* Phase 0 exists to stop this. No trade-offs → write the code.
+2. *Solution before problem.* If the reader doesn't understand the problem first, the design can't be judged. Problem leads, always.
+3. *Skipping Alternatives + Decisions.* These are the sections that carry the spec's value. A single inevitable path with no why-nots is a red flag.
+4. *Listing only the upside of a decision.* Record what gets harder too.
+5. *Polishing before drafting.* Get the skeleton down rough; rigor comes in revision. Don't stall on an unknown — file it as an open decision.
+6. *Letting it sprawl.* Skip the terseness pass and the spec goes unread. Cut ~30%; appendix the rest.
+7. *No owner, no status.* A spec nobody owns drifts; a spec with no status can't be triaged.
+8. *Editing a resolved decision in place.* Supersede, don't overwrite — the history is the value.
+9. *No implementation phases.* =spec-review= can't decompose the work into tasks and the spec fails the gate. Phase it, each step leaving a working tree.
+10. *Silently skipping a readiness dimension.* Each is answered or explicitly "N/A because…" — an unanswered dimension is a hidden decision the implementer inherits.