writing-specs

This skill speaks in host-neutral actions. Resolve them to your runtime's tools by reading the host tool map at ${CLAUDE_PLUGIN_ROOT}/hosts/<your-host>-tools.md (the leading variable is this plugin's root directory) — claude-tools.md on Claude Code, codex-tools.md on Codex.

writing-specs

Turn an owner-approved set of requirements into the on-disk spec definition-doc. This is the artifact step, distinct from the dialogue: the dialogue happens in discovery; this skill owns the artifact. The frontmatter linkage is machine-read, so it is emitted by the lib — never hand-written.

Precondition: the owner has approved the requirements (Discovery's HARD GATE). If they have not, stop and return to discovery — do not author a spec from un-approved requirements.

Spec content rules (consolidation, annexes, rulings, Amendments shape): ${CLAUDE_PLUGIN_ROOT}/skills/architect-spec/reference/spec-content.md.

Inputs (from discovery)

The approved: title, purpose, who it's for, functional requirements (EARS sentences, each with ≥1 acceptance criterion), significant unhappy-path behaviors (If/Then EARS, from the coverage checklist), non-functional requirements (outcomes + fit-criteria), the approved build board's saved path (the work-item's board/ folder) or the recorded skip, the owner's rulings for this piece, definition of done / success, assumptions & dependencies, constraints, out-of-scope, the craft calls made for the owner's veto, and size.

Flow

1. Mint the work-item (once; it is then frozen — CONVENTIONS §6.1):

   ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
   WORK_ITEM=$(python3 -B "$ROOT_DIR/lib/definition_doc.py" mint --title "<title>")
   

   Reuse the slug discovery hands you, or the existing slug if this spec already exists (a revision); never re-mint for the same work-item.

2. Resolve the path at the repo root (Phase 1 is in-repo). Pin --root to the repo top level so the spec can't land in a subdirectory regardless of the current working directory:

   ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
   ROOT=$(git rev-parse --show-toplevel)
   SPEC=$(python3 -B "$ROOT_DIR/lib/definition_doc.py" resolve-write \
     --work-item "$WORK_ITEM" --doc spec --root "$ROOT") \
     || { echo "the-architect: cannot place the spec safely (see message above) — not writing." >&2; exit 1; }
   

3. Emit the §3.1 frontmatter with the lib (a fresh spec is status: draft, gates.review: pending):

   ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
   python3 -B "$ROOT_DIR/lib/definition_doc.py" frontmatter \
     --doc spec --work-item "$WORK_ITEM" --size "<size>"
   

   Do not hand-write the frontmatter — the lib owns its shape and the gate/status invariants.

4. Fill the body from ${CLAUDE_PLUGIN_ROOT}/templates/spec.md: replace the {{frontmatter}} line with the emitted block, set the # {{Title}}, and fill every section from the approved inputs. Honor the template's contract:

   • Every statement ends with its source tag, plain text at the end of the statement. The template's "How to read this spec" section is the one home for the kinds of source and how a statement with two sources reads; fill it with only the sources this spec uses. A tag never cites transcript line numbers. Tags are for the owner and for the source check, an agent reading plain files; no script or validator reads them.
   • Write from the approved board and the rulings. Where the spec and the approved board disagree, follow discovery's step 5.
   • Functional requirements in EARS, numbered, one behavior each, each with ≥1 acceptance criterion (Given-When-Then for flows, rule bullets for constraints).
   • Significant unhappy paths as If/Then EARS, driven by the coverage checklist; record each area's disposition in the Dispositions table (## Coverage) at the end — not as an inline tag list inside the unhappy-paths section.
   • The Dispositions table (## Coverage) is one merged table: all nine unhappy-path coverage areas plus the initially-six happy-path dimensions (currently fifteen rows; the dimension list grows with the learning loop), four columns (Area | Disposition | Show-it? | Where / why), Disposition ∈ {Specify, Defer-to-build, N-A}, and Show-it? ∈ {Yes, No} (literal — only on N-A rows).
   • ## Amendments is always rendered, even when empty — its zero state is the single line _No amendments since the last full approval._
   • Non-functional requirements as outcomes with a fit-criterion.
   • Load-bearing mirror-facts carry a [cite: …] citation. A mirror-fact is a spec sentence asserting something about the EXISTING repo that the repo could contradict ("reuses/extends the existing X", "the current limit is N", "today the system does Y"). Apply the test — "Could today's repo contradict this sentence?" YES → mirror-fact → cite its repo source ([cite: <repo-relative-path>], or [cite: <path> § <anchor>] with <anchor> a literal substring in that file). A definition — a NEW behavior this spec itself defines, the owner's what — mirrors nothing and carries NO citation. Honor the noise budget: only load-bearing mirror-facts (ones the build relies on being true) get citations; incidental mentions don't. Citations stay rare — a citation-dense spec is usually leaking the build's how (CONVENTIONS §3.2).
   • UI/UX points at the approved build board's saved path, the board/ folder beside the spec, with its link, and never re-describes a screen in prose. When the board was skipped, the section says so in one sentence, with its source tag.
   • Plain language throughout, no technical how. Delete sections that genuinely don't apply (UI/UX for non-user-facing work; Glossary when there are no terms). Open questions is resolved or deferred before approval, then left empty or deleted — never kept with a placeholder under it.
   • Strip the author-guidance comments. The template carries <!-- AUTHOR GUIDANCE … --> blocks (the EARS explainer, the coverage checklist, the defer-promise note) — they are for you, not the owner. Delete every one. The delivered spec contains only owner-facing content.

   Write the assembled file to $SPEC.

5. Self-review (look at the written file with fresh eyes; fix inline — no re-review loop):

   • Placeholders & guidance: any {{…}}, "TBD", "TODO", or leftover <!-- AUTHOR GUIDANCE … --> comment? Fill or remove it — the owner sees none of it. (A [cite: …] provenance marker is a sanctioned spec construct (CONVENTIONS §3.2), not a leftover placeholder — never strip or flag it as {{…}}/TBD noise.)
   • EARS + anti-slop: does each functional requirement match an EARS pattern, state one behavior, avoid vague words, and carry an acceptance criterion? Split compound requirements; pin vague ones.
   • Provenance: does every load-bearing mirror-fact carry a [cite: …] citation whose path (and anchor, if any) resolves to a real repo source? Incidental facts and new definitions do NOT carry one — a citation-dense spec is leaking the build's how.
   • Source tags: does every statement end with a plain-text source tag that names a source listed in "How to read this spec", and does no tag cite a transcript line number? Does the spec agree with the approved board? Where it does not, follow discovery's step 5.
   • No tech leaked: any implementation detail (libraries, schemas, APIs) that belongs to the build's how? Move it out — the spec is the what. (A [cite: …] provenance marker is a sanctioned spec construct (CONVENTIONS §3.2), not leaked implementation detail — never strip or flag it as tech-leak or a path reference.)
   • Coverage: does the Dispositions table (## Coverage) disposition every row — all nine unhappy-path areas and all initially-six happy-path dimensions (Specify/Defer-to-build/N-A), with each Specify backed by a real UFR, every row carrying a Show-it? value — and are the significant unhappy paths actually addressed, not just the happy path? Is ## Amendments present (the zero-state line counts)?
   • Internal consistency: do acceptance criteria and the definition of done match the requirements? Any section contradict another?
   • Scope: focused enough for one work-item, or does it need decomposition?
   • Ambiguity: any requirement readable two ways? Pick one, make it explicit; repeat concrete nouns instead of "it/this".

6. Return to discovery with the path. Discovery runs the spec checks (skills/architect-discovery/reference/spec-checks.md) and owns the gate and the owner's final approval; this skill stops at "spec written and self-reviewed."

Size never changes the artifact class

A small spec and a large spec are the same artifact class. Four equivalences hold, always:

1. Same template. Both are filled from ${CLAUDE_PLUGIN_ROOT}/templates/spec.md. There is no short-form template.
2. Same home. Both land at the spec definition-doc path for their work-item, resolved the same way (definition_doc.py resolve-write --doc spec). There is no separate home for small specs.
3. Same anchor power. An issue's Anchor slot may cite a section of either, and the citation resolves by the same test. A small spec is not a weaker citation. Both halves of that test are mechanical: the dated approval an anchor resolves against is written by the approval path itself (set-gate records the date), so the equivalence holds mechanically end to end.
4. Same owner approval authority. Both are approved by the owner, recorded through the same set-gate call. There is no lesser approval.

Every spec gets the same three spec checks whatever its size, and a spec's size changes only which sections it carries. The advisor may size its own vet of it. None of this changes the artifact.

Empty sections are omitted, never filled. A small spec is shorter because it deletes the sections that genuinely do not apply — not because it keeps a heading and writes "N/A", "None", "TBD", "—", or a one-line restatement of the heading underneath it. A heading with nothing real under it is a defect at any size, and deleting it is the fix.

Exception — ## Amendments: This section is always kept. Its zero state — the explicit no-amendments line — is something real, not a placeholder. Do not delete it under the empty-sections rule above.

Rationalization table

Excuse	Reality
"I'll hand-write the frontmatter, it's just YAML"	The lib owns the §3.1 shape + gate/status invariants. Use definition_doc.py frontmatter.
"I'll resolve the path from the current dir"	Pin --root "$(git rev-parse --show-toplevel)" — a subdir cwd would misplace the spec.
"I'll re-mint the slug to be safe"	The slug is frozen at creation (§6.1). Reuse it for a revision; never re-mint.
"Plain prose is fine for requirements"	Functional requirements are EARS + acceptance criteria. That's the verifiable contract.
"A little tech detail clarifies it"	Tech is the build's how. Keep the spec to the what.
"Owner approved the idea, I'll author straight off"	Author only from the approved requirements. If they weren't approved, back to discovery.
"I'll just assert the repo does X, everyone knows it"	A load-bearing mirror-fact needs a resolving [cite: …] to its repo source. A fabricated repo fact is a known failure class — cite it or don't assert it.
"It's a small spec, I'll use a shorter format"	A spec's size changes only which sections it carries, never the artifact class: same template, same home, same anchor power, same owner approval authority.
"I'll keep the heading and write N/A under it"	Empty sections are omitted, never filled. A heading with nothing real under it is a defect at any size — delete it.
"The Amendments section is empty, I'll delete it like any empty section"	## Amendments is always rendered; its zero state is the explicit no-amendments line — that is real content, not an empty section.
"This annex just spells out what the spec meant"	An annex elaborates decisions the core already makes; a new opinion amends the core. Annex smuggling is a named spec-check finding class.
"The chat said it more clearly than the board, so I'll write it the chat's way"	Write from the approved board and the rulings. Where the spec and the board disagree, follow discovery's step 5.
"I'll cite the transcript line so the source is exact"	A tag never cites transcript line numbers. Name the board, the Canon entry, the framing, or craft.