writing-specs

writing-specs — Technical Specification in XML

Drives the creation of a technical specification and emits it as an XML document saved to specs/<slug>/spec.xml. This XML is the planning contract — readable and versionable — later consumed by the running-spec-dev skill, which derives tasks.json from it and runs the development loop.

When to use

• Specify a feat or fix before implementing.
• Record goal, scope, requirements, steps, and acceptance criteria in a structured way.
• Produce a versionable artifact that serves as input to running-spec-dev.

Flow

1. Gather the essentials. Make sure you have:

   • Work type: feat or fix.
   • The goal (the "why") and the desired outcome.
   • The scope — what's in and, explicitly, what's out.
   • Known constraints (technical, compatibility, data).

   If something critical is missing and can't be inferred from the code, ask. Otherwise, record the best hypothesis and mark the requirement with status="hypothesis".

2. Investigate the code. When the spec touches existing modules, read them and cite real file:line in <context><reference> — never invent paths.

3. Fill in the template. Read references/spec_template.xml and produce the spec by replacing the {placeholders}. Non-negotiable rules:

   • Well-formed XML: closed tags, quoted attributes, escaped specials (& < >).
   • Stable IDs: R1, R2… for requirements; number="1", "2"… for steps.
   • Relative dates become absolute (use the current session date in created).
   • Remove optional sections (<technology_stack>, <open_questions>) if unused.

4. Save. To specs/<slug>/spec.xml (create the directory). The <slug> is the spec's identity (the folder carries it, not the file name): kebab-case, short, and descriptive enough to identify the work on its own — e.g., code-reviewer-skill, fix-token-refresh; avoid generic ones like spec, new-feature, or change. Don't embed the type in the slug (it's already a spec attribute and becomes the branch feat/<slug>|fix/<slug>). Confirm with the user before overwriting an existing spec.

5. Validate (feedback loop). Run:

   python "${CLAUDE_PLUGIN_ROOT}/skills/writing-specs/scripts/validate_spec.py" specs/<slug>/spec.xml
   

   Fix and re-validate until the validator exits with code 0. Only then proceed.

6. Summarize. 2–4 lines of what was specified, plus any open <open_questions>. If it makes sense, suggest running running-spec-dev pointing at the spec.

Structure of spec.xml

Root <spec type="feat|fix" slug="..." created="YYYY-MM-DD">, with children:

Tag	Required	Content
<title>	yes	Short, specific title
<overview>	yes	Prose: problem + desired outcome
<scope>	yes	<includes> / <excludes>
<context>	yes	`<reference type="file
<technology_stack>	no	<item> per relevant dependency/constraint
<requirements>	yes	testable <requirement id priority status>
<implementation_steps>	yes	<step number><title><tasks> (becomes tasks.json)
<success_criteria>	yes	verifiable <criterion id>
<open_questions>	no	unanswered <question>

Enums

• type: feat | fix
• priority: high | medium | low
• status: confirmed | hypothesis | discarded

The canonical template is in references/spec_template.xml.

Best practices

• Testable requirements and criteria — avoid "must be fast"; prefer metrics.
• <implementation_steps> is what becomes trackable tasks: each <step> should have concrete, orderable tasks (the natural dependency is the order of number).
• Don't duplicate what the code already documents; point to it via <reference>.
• Keep the XML a lean contract, not exhaustive documentation.