create-dev-spec

Files (3)

• SKILL.md
• interview-guide.md · references/
• spec-template.md · references/

SKILL.md (first lines)

# create-dev-spec — From Rough Requirement to Approved Specification

## Core Principle

A specification written alone is a guess with headings. This workflow makes the spec a
**co-authored** document: you bring structure, the questions the user has not asked
themselves yet, and concrete proposals; the user brings intent, domain knowledge, and the
final say. Nothing that shapes the spec is decided silently — every gap becomes a question,
every question gets your best proposal plus room for the user's own answer, and every answer
is recorded as a decision the spec can cite.

The output is two files:

| Artifact | Path | Purpose |
|---|---|---|
| Draft | `docs/draft/spec_<slug>.md` | Everything learned so far, written for review |
| Spec | `docs/specs/<slug>.md` | The final document, produced only after explicit approval |

`<slug>` is a 2–4 word kebab-case description of the requirement (e.g. `customer-csv-export`),
proposed by you and confirmed by the user during the interview.

**Explicit invocation.** This skill starts only when it was named — `/create-dev-spec`,
`/cc-ai-dev:create-dev-spec`, the name in the prompt, or a hand-off from another skill such as
`create-dev-plan`. A request that merely describes spec-shaped work ("spec this out", a rough
feature idea) is handled as an ordinary request without this workflow.

## Flow Overview

```
Phase 1  Orientation        — understand the requirement                         (step 1)
Phase 2  Collection         — open questions, gaps, own remarks and ideas         (steps 2–3)
Phase 3  Interview          — one structured question per item, with proposals   (step 4)
         ↺ Follow-up loop   — new questions from answers → back into Phase 3     (step 5)
Phase 4  Draft              — write docs/draft/spec_<slug>.md                    (step 6)
GATE     Draft review       — STOP; user edits, discusses (→ Phase 3), or approves (steps 7–8)
Phase 5  Absorb edits       — re-read the draft from disk, reconcile              (step 9)
Phase 6  Specification      — write docs/specs/<slug>.md                         (step 10)
```

## Critical Rules (read before every phase)

1. **Every open point goes through the structured question tool.** Use your runtime's
   tool for structured user questions (in Claude Code: `AskUserQuestion`), never a prose
   question in a normal reply. Prose questions get answered partially, in the wrong order,
   or not at all; the tool guarantees one visible decision per item, with the options the
   user is choosing between spelled out.

2. **Every question carries your own proposals and a free-form escape.** For each item
   offer 2–4 concrete answers you would actually recommend, the recommended one first and
   marked as such, and make sure the user can always answer with something entirely their
   own. If the tool adds a free-text option automatically (Claude Code's tool does), do not
   duplicate it; if it does not, add "Something else — I'll describe it" explicitly. A
   question without proposals pushes the thinking back onto the user; a question without an
   escape hatch pretends your proposals are exhaustive.

3. **The draft gate is mandatory and only explicit approval passes it.** After writing the
   draft you STOP. The user may edit the file, raise points in chat, or approve. Only an
   unambiguous approval of the draft moves the workflow to Phase 5. "Looks good so far",
   "continue", "ok" after a question, or silence are not approvals — see the Gate section.

4. **Re-read the draft from disk before writing the spec.** The user may have edited the
   file without saying so. What is on disk wins over what you remember writing; reconcile
   conflicts explicitly (Phase 5).

5. **Never commit, never overwrite silently.** You create and edit the draft and the spec;
   the user commits. If `docs/specs/<slug>.md` already exists, ask before replacing it.

6. **Urgency waives nothing.** "Just write the spec", "we know what we want", "skip the
   questions" are not permission to skip Phase 2–3 or the gate. Acknowledge the hurry, then
   run the workflow at speed: fewer but sharper questions, batched where independent, never
   zero. A spec that skipped the interview is exactly the guess this workflow exists to
   prevent.

## Precondition — Interactive User Required

This workflow has no non-interactive mode. Phases 3 and the gate need a person answering;
inventing their answers would replace the user's intent with yours, which is the one thing a
spec must not do.

**Judge the run, not your own message channel.** The precondition is unmet only when the
whole run has no user behind it: you were dispatched by a script, CI, cron, or another
agent whose final output is consumed by a program, and no human will read your questions.

**When it is unmet:** run Phase 1 and Phase 2 only — both are read-only — then STOP and reply
with a `Blocked — interactive user required` handoff instead of starting the interview. The
handoff is your reply, not a file: do not create `docs/draft/` or `docs/specs/` content.
Include the Phase 1 summary, the full Phase 2 list of questions and ideas, and one line
stating that an interactive user can resume at Phase 3 with that list.

## Phase 1 — Orientation

Goal: understand what is being asked well enough to see what is missing.

1. Read the requirement as given — message text, linked ticket, attached file, referenced
   docs. If it points at a codebase, look at the affected area only as far as needed to
   understand terms and existing behavior; this is orientation, not analysis.
2. Write a short **orientation summary** (5–10 lines): what the user wants, for whom, why,
   and which parts of the system it touches. State the language the requirement was written
   in — it is the default for the interview and the first thing you will confirm.
3. Do not propose solutions yet and do not ask questions yet. Collect first, ask second;
   a question asked before you have the whole picture is usually the wrong question.

## Phase 2 — Collection

Goal: a complete, numbered list of everything that must be settled before the spec can be
written. Two lists, built separately so neither crowds out the other.

**2a — Open questions, ambiguities, gaps** (`Q-1`, `Q-2`, …). Walk the checklist in
[`references/interview-guide.md`](references/interview-guide.md#question-categories):
scope and boundaries, actors and permissions, inputs and outputs, business rules, edge
cases and error behavior, data and persistence, integration points, non-functional needs,
migration and rollout, testing and acceptance, constraints. For each category ask
yourself: *could two competent engineers implement this differently and both claim to have
met the requirement?* If yes, that is a question.

**2b — Own remarks and ideas** (`I-1`, `I-2`, …). Things the user did not ask for but
should decide on: a simpler alternative, a risk you see, a related capability that is cheap
now and expensive later, a convention in the codebase the requirement conflicts with. Each
idea is a proposal the user may reject; it is listed so the rejection is a recorded decision

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store