---
name: specify
model: inherit
effort: high
agents: [critic, researcher, strategist, analyst, devils-advocate]
description: >
  Use to turn a raw feature idea into a reviewed spec.md — a lightweight Socratic interview
  front (capture the idea, deep-dive the problem) merged with a full product spec (context,
  goals, user stories, acceptance criteria, NFRs, KPIs). Triggers on "specify {slug}",
  "spec for {slug}", "write the spec", "capture this idea", "draft requirements for {slug}",
  "/awesome-sdd:specify {slug}".
  Opens by setting the interview-depth dial (easy/medium/hard), drafts from templates/spec.md,
  validates each acceptance criterion Socratically, runs a clean-context critic, then writes
  docs/features/{slug}/spec.md. The ideation analyses (competitive research, strategic approaches,
  multi-perspective review, devil's-advocate) run as named subagents gated by the depth dial —
  easy skips them, hard runs the full suite.
---

**English only:** Write all conversation, questions, options, progress updates, handoffs, reports, and generated document prose in English. Apply the [language policy](../_shared/artifact-language.md) even when settings or source documents use another language.

**Host runtime:** Resolve and reuse [host capabilities](../_shared/host-capabilities.md) before this protocol. Dispatch roles through the [agent roster](../_shared/agent-roster.md); render questions and handoffs through that runtime. Model/effort frontmatter applies only where the host supports it.

# Skill: specify

Turns a one-line idea into a reviewed `spec.md`: a lightweight interview captures and stress-tests the idea, then the skill drafts a product spec (context → goals → user stories → acceptance criteria → NFRs → KPIs), validates it Socratically, and runs a clean-context critic before writing. Less typing, more reviewing. This file is the spine; detail lives in `references/`.

The Socratic machine, the critic, and the size matrix are **shared** — this skill keeps only its deltas:
→ [`../_shared/socratic-loop.md`](../_shared/socratic-loop.md) · [`../_shared/critic.md`](../_shared/critic.md) · [`../_shared/size-matrix.md`](../_shared/size-matrix.md) · [`../_shared/ask-style.md`](../_shared/ask-style.md)

Depth governs question volume + autonomy (and which ideation analyses run) → [`../_shared/interview-depth.md`](../_shared/interview-depth.md).

Document prose follows the project's `artifact_language` setting — section headings, frontmatter and machine tokens stay English → [`../_shared/artifact-language.md`](../_shared/artifact-language.md).

## Owner

PM + Tech Lead (co-authors). PM drives goals / non-goals / KPIs; Tech Lead drives context patterns and the acceptance-criteria coverage.

## Inputs

- `<slug>` — kebab-case feature slug.
- (Optional) `CONTEXT.md` — the two-level glossary: read **both** repo-root (project-wide) and `docs/features/<slug>/CONTEXT.md` (feature-scoped); per-feature wins on conflict → [`../glossary/SKILL.md`](../glossary/SKILL.md). If present, its roles/terms are canonical and override anything that contradicts them.
- `docs/features/<slug>/.size` — depth hint (MVP vs Full per the size matrix). **Read if present; established here if absent** (step 1 classifies + writes it), so downstream stages never silently default to M. `classify-size` re-classifies when scope changes.
- (Optional) `docs/idea-brief.md` — read before repeating discovery; identity, readiness and reuse
  follow [`./references/brief-reuse.md`](./references/brief-reuse.md). A brief is not mandatory.
- (Optional) prior notes / a reference module / a ticket the user already has.

## Protocol

1. **Ensure the settings file (first thing, after this skill's own gate).** If `.claude/sdd.local.md` is absent, create it now from the canonical template — documented defaults + the self-documenting body — and patch `.gitignore`; if it exists, read it and never overwrite. The one procedure lives in [`../_shared/settings-file.md`](../_shared/settings-file.md). Creating is unconditional; **changing values is only ever offered by [`config`](../config/SKILL.md)**. Say one line: «`.claude/sdd.local.md` created with documented defaults — `/awesome-sdd:config` to tune it». **Then read context + set the interview depth.** If a `CONTEXT.md` exists (read **both** repo-root and `docs/features/<slug>/` — per-feature wins on conflict), load its `## Glossary` as session state (canonical roles + terms). If `.size` exists, read it to size the spec's depth; **if it's absent, establish it now** — run the **`classify-size` protocol inline** (the canon: [`../classify-size/SKILL.md`](../classify-size/SKILL.md) + the mapping in [`../_shared/size-matrix.md`](../_shared/size-matrix.md)); reuse known signals and ask only missing signals, one short question at a time (at `easy` depth, take the matrix default and record it in the assumptions ledger), and write `docs/features/<slug>/.size` **+ `.route`** (the route defaults from the size — XS/S→`quick`, M→`standard`, L/XL→`full` — and is confirmed as a separate simple choice when confirmation is needed, per the Routes table in [`../_shared/size-matrix.md`](../_shared/size-matrix.md)) — so every later stage reads a real size instead of silently defaulting to M (the gap that otherwise surfaces only at `plan-tests`). `classify-size` stays the utility to re-classify when scope changes. If `docs/architecture-map.md` exists (from `survey`), read it so the spec is **architecture-aware** — it informs §1 Context, §2 Constraints, and §3 Non-goals (what the existing system already does / can't do). Absent → suggest running `survey` first, but proceed (the spec is product-level and can be captured without it). **Do not leak the map's tech into §5 AC** — AC stay business-observable; the map shapes constraints, not acceptance criteria. **Resolve discussion depth** from the explicit or saved preference per [`../_shared/interview-depth.md`](../_shared/interview-depth.md), otherwise medium; no repeated depth menu. Keep completeness checks unchanged and every question short. **Bootstrap `spec.md`:** copy [`./templates/spec.md`](./templates/spec.md) to `docs/features/<slug>/spec.md` now (frontmatter stamped, sections still placeholders) — from here on every resolved section lands in that file immediately, never held in memory until the end → [`../_shared/write-and-commit.md`](../_shared/write-and-commit.md).
2. **Reuse or capture the idea.** First apply [`./references/brief-reuse.md`](./references/brief-reuse.md): read the existing brief, check scope/readiness, reuse accepted answers and relevant evidence, and ask only specification gaps. For an already supplied idea, do not ask the user to repeat it. Without a usable brief, the standalone interview front follows: if the raw idea is absent, ask for it in 1–3 sentences; otherwise reuse the user's original words as the baseline. Then a Socratic deep-dive across problem clarity / success criteria / constraints / strategic fit, delivered one question at a time — its volume scales with the depth dial (easy: only the few un-inferable ones, then a stated-assumptions ledger; medium: 3–5; hard: walk every angle, foreground each trade-off). Phrase every question per [`../_shared/ask-style.md`](../_shared/ask-style.md).
3. **Ideation suite (reuse first, then depth-gated subagents).** Apply [`./references/brief-reuse.md`](./references/brief-reuse.md) before dispatch: reuse covered signals at every depth, run only remaining/reopened gaps, and never manufacture absent RICE/matrix outputs. Without a usable brief, run the ideation analyses as role dispatches gated by the **interview-depth dial** (size as a secondary trimmer) → [`./references/ideation.md`](./references/ideation.md): **easy** → skip the suite (deep-dive only; the chosen approach is recorded as a ledger assumption); **medium** → `researcher` (competitive/web) + `devils-advocate` (failure-mode mode); **hard** → full suite `researcher` + `strategist` (3 approaches) + `analyst` (multi-perspective) + `devils-advocate`, then the assistant-proposed RICE/feasibility confirm. Analyses stay **product-level** (no tech names — that's `design`); the confirmed recommendation becomes §1 ¶3. Dispatch with role `<name>` via the resolved runtime per [`../_shared/agent-roster.md`](../_shared/agent-roster.md) (runtime-selected generic worker or inline self-check fallback); `researcher` needs web — accept its `RESEARCH_LIMITED` output as a noted gap if web is unavailable.
4. **Reconcile the glossary in-flow (a hard rule, at every depth).** On every new or unknown domain term that surfaces in the interview or the draft, invoke `glossary <slug>` for it **immediately** — compare it against `CONTEXT.md` and add/update the definition before continuing. By the time the spec is written, every §4 role and §5 domain term is already glossary-canonical; the glossary is never a deferred batch. (Plan-mode nuance: still decide add/update per term in-flow; if writes are blocked until the spec write-point, persist the reconciled terms together with the spec, but never skip the per-term compare.)
5. **Ask which extra channels to read** (multi-select `AskUserQuestion`): reference module code / project docs / MCP-Atlassian (Confluence/Jira) / knowledge-base / none. For each picked channel ask the **specific** path/query — no silent broad scans.
6. **Read the template + draft §1–§8.** Read [`./templates/spec.md`](./templates/spec.md) (its `<!-- instruction -->` comments are the per-section contract). Draft per [`./references/draft-generation.md`](./references/draft-generation.md): per-section sources, the **5 AC coverage types** (happy / error / authorization / domain invariant / cross-context), and the **stack-agnostic forbidden-token** rule for acceptance criteria. §1–§3 (not per-item walked) go into `spec.md` as soon as they are drafted.
7. **Socratic validation.** Walk §4 US → §5 AC → §6 NFR → §7 KPI with the shared 4-state machine (per-decision question volume scales with the depth dial — at easy, the un-asked decisions land in the assumptions ledger for small, relevant recaps; ask about an uncertain assumption individually). Specify delta → [`./references/socratic.md`](./references/socratic.md): accept a naturally requested additional criterion without forcing an extra menu option; the §5 coverage gate enforces **two floors** after drops/OQ-migrations — (a) ≥1 AC of each of the 5 coverage types, and (b) **≥1 AC per retained §4 user story** (regenerate/add a replacement if a type *or* a user story is left empty). **Both are floors, not dials — enforced at every depth;** only the question volume scales. The (b) floor closes the §4→§5 link so the downstream `sequences` use-case coverage + `review` trace can't be undermined by a user story that lost its only AC. Maintain the edits-log. Write each resolved part into `spec.md` as the answer arrives (§8 gets each `save_as_oq` row as it happens).
8. **Critic + self-check + commit.** Dispatch the [`critic`](../../agents/critic.md) agent — role `critic` via the resolved runtime (**model and effort per the roster and resolved runtime**; context isolation per [`../_shared/agent-roster.md`](../_shared/agent-roster.md)) — with the specify delta in [`./references/critic.md`](./references/critic.md) (over [`../_shared/critic.md`](../_shared/critic.md)) — inline the edits-log + current owner corrections, it Reads `docs/features/<slug>/spec.md` from disk + `CONTEXT.md` + the idea source (including the reused brief) itself and checks preservation of accepted constraints and evidence limits. Resolve findings via `AskUserQuestion` (Accept revert / Accept amendment / Override-with-rationale → §1 ¶4 bullet). Patch `spec.md` on disk with every accepted revert/amendment as it is resolved. Run the forbidden-token regex scan over the file as the F6 backstop (glossary already reconciled in-flow per step 4). **Register on the roadmap:** in `docs/roadmap.md` (via `roadmap`) set the matching step's `Status: spec'd` and link this feature folder; no matching step → append one (source anchor = this spec). (If there's no roadmap yet, skip — it's optional.) **Commit per [`../_shared/write-and-commit.md`](../_shared/write-and-commit.md)** — only after the critic + F6 scan pass; one commit per document: `specify: <slug> spec.md`, `specify: <slug> .size+.route` (one commit), `specify: <slug> CONTEXT.md` (each glossary file the in-flow reconciliation changed), `specify: roadmap.md` — skipping any that didn't change. Then **emit the stage-handoff block** per [`../_shared/handoff.md`](../_shared/handoff.md) — *What I did* + *Review* (`spec.md`, `.size`, `.route`) + *Run next* — **resolve the next stage per `.route`** (the Routes table in [`../_shared/size-matrix.md`](../_shared/size-matrix.md); route-resolved variant in handoff.md): forward `/awesome-sdd:clarify <slug>`; `clarify`'s N/A condition = **zero §8 open questions and no AC flagged ambiguous**, skip target `/awesome-sdd:ux-flows <slug>` (on `quick` — auto-skip with the reason + inverted `↳ or`; on `standard` — offer the `↳ or`; on `full` — no skip line). When clarify is legally skipped, **carry the next condition forward**: evaluate `ux-flows`' N/A condition too (no human-facing UI — every §4 actor a system/service, or the repo has no UI at all, per [`../_shared/size-matrix.md`](../_shared/size-matrix.md)) → holds ⇒ the skip target becomes `/awesome-sdd:design <slug>`. (If `critic` is unavailable, fall back to an available authorized generic worker (otherwise an inline self-check) with the same delta.)

## Definition of Done

- `docs/features/<slug>/spec.md` written; all sections filled (or `<!-- N/A: reason -->`).
- `docs/features/<slug>/.size` **and `.route`** exist after this stage (read if present, else classified + written here) — the backbone no longer reaches `design`…`plan-tests` on a silent M default, and every handoff resolves per a real route.
- §5 holds ≥1 AC of each of the 5 coverage types after drops/OQ-migrations, **every §4 user story has ≥1 AC** (the use-case floor — no retained US left with zero ACs), and **0 forbidden tokens** (HTTP verbs / URL paths / status-code numerics / `module.error_name` strings / JSON fragments / SQL constructs).
- §4 roles match the `CONTEXT.md` glossary exactly (no invented `user`/`admin`).
- §8 Open Questions each carry owner + due (no lone «TBD»).
- Edits-log maintained; critic ran on the post-Socratic `spec.md` read from disk; every finding resolved or overridden.
- `spec.md` was bootstrapped in step 1 and filled section by section; after the self-check, one commit per changed document (`spec.md`, `.size`+`.route`, `CONTEXT.md`, `roadmap.md`), SHAs listed in the handoff — per [`../_shared/write-and-commit.md`](../_shared/write-and-commit.md).
- The step-8 critic + the forbidden-token regex backstop are this skill's **structural self-check** ([`../_shared/self-check.md`](../_shared/self-check.md)); its result is reported in the handoff.

## Anti-patterns

- **Inventing owner answers.** Reuse confirmed brief/conversation answers; ask about missing consequential decisions. Repeating a settled interview is not required, and headless execution does not license new guesses.
- **Naming concrete technologies in §1–§3** (a specific datastore, broker, framework, or library). The spec is WHAT + WHY; technology choices belong to `design`.
- **Implementation leak in AC** — HTTP/status/error-code/SQL detail. That mapping lives in `api` and `decide-adr`.
- **Running the full ideation suite at `easy` depth** — over-production. The depth dial gates it (easy skips entirely; medium runs research + devil's-advocate; hard runs all). Feature size only *trims volume* within a level — it's no longer the gate.
- **Holding the whole spec in memory and writing it once at the end** — a lost session loses every decision. Bootstrap in step 1, write each section as it resolves.
- **Inventing competitors / RICE numbers** to fill the ideation pass. Better `N/A — internal tool` than fake research; accept the `researcher` agent's `RESEARCH_LIMITED` over fabricated rows.

## References & template

- [`./references/ideation.md`](./references/ideation.md) — depth-gated ideation orchestration: which named subagent (`researcher` / `strategist` / `analyst` / `devils-advocate`) runs at which level, what each returns, how outputs feed the spec.
- [`../_shared/interview-depth.md`](../_shared/interview-depth.md) — the easy/medium/hard dial set in step 1 (question volume, autonomy, which analyses run).
- [`./references/draft-generation.md`](./references/draft-generation.md) — per-section sources, 5 AC coverage types, stack-agnostic forbidden tokens.
- [`./references/socratic.md`](./references/socratic.md) — specify's delta over the shared Socratic loop.
- [`./references/critic.md`](./references/critic.md) — specify's delta over the shared critic (F6 = forbidden tokens).
- [`./templates/spec.md`](./templates/spec.md) — output scaffold; inline comments are the per-section generation contract.