To Spec

To Spec

Synthesize the spec from what grounding, intake, and research evidence already surfaced; do not interview. Anything genuinely unanswered goes through step 4.

Process

1. Read the codebase-design vocabulary (skills/codebase-design/SKILL.md) before writing a line. Reuse its module, interface, seam, adapter, depth, and locality terms exactly; never substitute component, service, boundary, or API for module or interface.
2. Name the seam(s) this run will exercise before drafting any section. Existing seams are preferred to new ones, at the highest point possible; the ideal number is one. Record them under ## Implementation decisions.
3. Do not include specific file paths or code snippets in the spec body — they may end up being outdated very quickly. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts.
4. Never run the timed-ruling protocol yourself or wait on the human: return every open question to the orchestrator, one line each — RULING NEEDED: <question> | options: <a | b> | default: <option> — <why> — and it runs the protocol (skills/architect/SKILL.md ## Timed-ruling protocol). Rulings already present in your dispatch context are decided; record each as an ## Assumptions entry. (Direct orchestrator invocation only — /architect-fast: run the protocol yourself as that lane records.)
5. Shape the spec on the template below and write it to docs/spec/<run>.md in your working tree. Do NOT commit it and do NOT create or update the tracking issue — the spec commit and the tracking-issue update (spec pointer, assumptions digest, or the markdown-mode equivalent in skills/architect/tracker.md ## Command mapping) are orchestrator actions after you return. End your reply with SPEC DRAFT: <path> plus any RULING NEEDED: lines.

Template

Write the sections below in this order; the names are load-bearing for hardening and decomposition, so keep them exact.

• ## Goal — what the run adds and why, from the reader's side.
• ## Target flow (optional) — a short numbered sequence, only when the run reorders or replaces a multi-step process; omit for additive or single-surface runs.
• ## Non-goals — what the run deliberately leaves unchanged.
• ## Assumptions — every timed-ruling default this run applied, one line each, dated.
• ## Implementation decisions — modules, interfaces, and the seam(s) from step 2, described, never pathed; the one place a prototype snippet may appear, per step 3.
• ## Validation strategy — how the run's own checks and the closing review confirm the seam(s) hold; name the check-runner and closing review, never new grading machinery.
• ## Domain language — new or changed vocabulary this run introduces, defined once.
• ## Open human decisions — anything unresolved once the timed-ruling protocol's timer expires; empty at freeze.
• ## Verified facts — every claim sourced outside this conversation: source, date fetched, fact supported.
• ## Preflight evidence — tool, auth, and repo-state evidence gathered before decomposition.