zwrose

writing-specs

Use to author the on-disk `spec` definition-doc once an owner has APPROVED a set of requirements, normally from the `discovery` skill. Mints the work-item slug and writes the self-reviewed spec. Does NOT elicit requirements (that is `discovery`) or design the technical approach (that is the build).

zwrose 1 Updated 1mo ago

Resources

1
GitHub

Install

npx skillscat add zwrose/superheroes/writing-specs

Install via the SkillsCat registry.

SKILL.md

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.