create-spec

name	create-spec
description	Use this skill when starting or updating a spec for a non-trivial change — a new feature, a refactor, a high-blast-radius change, or an ambiguous solution space — or when returning to one. It walks the UI/UX → system-design spec → approve → plan flow, points to the template, and covers the spec-status gate and the distillation step on completion.

create-spec

Turn a task into the single durable doc before writing code, so the design is legible and the plan that implements it is reviewable. The spec is the only committed doc per feature — execution tracking lives in plan mode (ephemeral), not in a committed *_implementation.md.

When to use

• A change is non-trivial: new behavior, a refactor, high blast radius, or an unclear solution space.
• You are resuming work and need to find or update the existing spec.

Do not use it for a one-line fix or a change with an obvious, local scope — that is overhead.

Steps

1. Capture WHAT (product). If user-facing, start from docs/ui-ux.md (template: docs/templates/ui_ux_template.md). The system design is derived from it.
2. Design. Write docs/<feature>_system_design.md from docs/templates/system_design_template.md: context, goals, success criteria, key decisions, alternatives, risks. It starts at Status: Draft. This is the durable doc — do not also create an implementation doc.
3. Read before proposing. Check docs/decisions/ (don't re-propose a rejected option; grep the folder for superseded / rejected records — index in docs/decisions/README.md) and docs/anti-patterns.md (don't repeat a known mistake).
4. Approve (the gate). Ask the developer to review the spec and flip it to Status: Approved. An Approved spec is a contract: implement it, don't re-litigate the design.
5. Plan & execute. Hand the approved spec to /plan. The plan is the execution tracking — it lives in plan mode (ephemeral, ~/.claude/plans/), not a committed doc. Execute with TDD (Red → Green → Refactor → verify each Success Criterion). The spec's ## Tests table stays design-time acceptance intent — realized tests and pass/fail live in the test suite and the verify gate.
6. Distill on completion. When the spec reaches Status: Implemented, add durable WHY as an append-only ADR record in docs/decisions/ and move durable HOW to docs/agent_rules/ (see the template's "Distillation on Completion").

The spec-status gate (when /plan picks up a spec)

/plan's first action is to read the spec's Status:

• Approved → proceed straight to plan + code. Treat it as a contract; don't propose "refining" it, don't ask meta-questions. Deferred open questions are not blockers.
• Not approved → ask exactly one thing: treat it as approved and implement as-is, or refine the spec first? — then proceed accordingly. No other process questions.

Checklist

• One fact, one genre — no rationale duplicated across docs.
• Acceptance criteria are observable and checkable, and each maps to a row in ## Tests.
• The spec carries a Status and names a verify step.
• Out-of-scope is explicit.
• No committed implementation doc was created — the plan lives in plan mode.

What this skill does NOT do

• It does not write production code.
• It does not create a docs/<feature>_implementation.md (or any impl-doc) — the plan is ephemeral.
• It does not create every template "because it exists" — create the smallest useful set.

Reference

• Genres + routing: docs/index.md
• Template: docs/templates/system_design_template.md
• Sub-agent that fills specs under a write scope: .claude/agents/spec-writer.md