specify
/specify
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}", "/sdd:specify {slug}", "напиши специфікацію {slug}", "опиши вимоги", "зафіксуй ідею". Opens by setting the interview-depth dial (easy/medium/hard), drafts from templates/spec.md, validates each acceptance criterion Socratically, runs a clean-co
- Author
- genkovich ↗
- Repository
- sdd ↗
- Licence
- MIT
- Last repository change
- 15.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
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}", "/sdd:specify {slug}", "напиши специфікацію {slug}", "опиши вимоги", "зафіксуй ідею". Opens by setting the interview-depth dial (easy/medium/hard), drafts from templates/spec.md, validates each acceptance criterion Socratically, runs a clean-co
Triggers from the description
Original author 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}", "/sdd:specify {slug}", "напиши специфікацію {slug}", "опиши вимоги", "зафіксуй ідею". Opens by setting the interview-depth dial (easy/medium/hard), drafts from templates/spec.md, validates each acceptance criterion Socratically, runs a clean-co
How it works
- Owner
- Inputs
- Protocol
- Definition of Done
- Anti-patterns
- References & template
SKILL.md preview
---
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}",
"/sdd:specify {slug}", "напиши специфікацію {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.
---
# 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 — `/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)); the four signals fold into one bundled `AskUserQuestion` here (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 in the **same** bundled question, 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. **Then set the interview depth (the opening question):** read `interview_depth` from the settings file ensured in the first sentence of this step (else default medium), and — unless a `--depth=easy|medium|hard` arg was passed (which skips the question) — ask ONE depth-selection `AskUserQuestion` phrased per [`../_shared/ask-style.md`](../_shared/ask-style.md), with the saved/medium value as the «(Recommended)» first option, overridable per run. The chosen level governs the step-2 deep-dive volume, the step-3 ideation suite, and the step-7 Socratic volume → [`../_shared/interview-depth.md`](../_shared/interview-depth.md). (Completeness — §5's 5-type AC floor — is unaffected by depth.) **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 in batches of 2–3 — 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 named-subagent 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` (`sdd:researcher`, competitive/web) + `devils-advocate` (`sdd:devils-advocate`, failure-mode mode); **hard** → full suite `researcher` + `strategist` (`sdd:strategist`, 3 approaches) + `analyst` (`sdd:analyst`, multi-perspective) + `devils-advocate`, then the Claude-proposed RICE/feasibility confirm. Analyses stay **product-level** (no tech names — that's `design`); the confirmed recommendation becomes §1 ¶3. Dispatch with `subagent_type: "sdd:<name>"` per [`../_shared/agent-roster.md`](../_shared/agent-roster.md) (`general-purpose` 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 a batch veto). Specify delta → [`./references/socratic.md`](./references/socratic.md): AC has a 5th option «Add another AC»; 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 section into `spec.md` right after its last decision resolves (§8 gets each `save_as_oq` row as it happens).
8. **Critic + self-check + commit.** Dispatch the [`critic`](../../agents/critic.md) agent — `subagent_type: "sdd:critic"` (**model per `judgment_model`**, effort `high` — `xhigh` on L/XL via `CLAUDE_CODE_EFFORT_LEVEL`; clean-isolated context 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 `/sdd:clarify <slug>`; `clarify`'s N/A condition = **zero §8 open questions and no AC flagged ambiguous**, skip target `/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 `/sdd:design <slug>`. (If `critic` is unavailable, fall back to a `general-purpose` Agent 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.
Files in this package (7)
- SKILL.md 17 KB
- references/brief-reuse.md 4 KB
- references/critic.md 3 KB
- references/draft-generation.md 4 KB
- references/ideation.md 9 KB
- references/socratic.md 3 KB
- templates/spec.md 7 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · genkovich/sdd | 90 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| sentimony/agentic-workflow | 100 | MIT |
| JoDi-27/JoDi-SDD | 100 | MIT |
| xoai/sage | 100 | MIT |
| ghaida/intent | 100 | CC0-1.0 |
| rikdc/claude_code_template | 100 | MPL-2.0 |
| zte-aicloud/co-omnispec | 95 | MIT |
| YnotnaUK/ai-skills | 90 | MPL-2.0 |
Database snapshot: 13.11.2026 · package version 3e00854af8d4 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100write-prd
Use to turn a raw feature idea into a reviewed PRD.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 "/sdlc:write-prd {slug}", "write… - 90sdlc-specify
Create or update a feature specification (what and why, no implementation) in specs/NNN-slug/spec.md. Use for T3 features, when the user says 'spec this' or 'write a spec', or when requirements for existing behaviour change. - 100pm-write-spec
Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document, scoping a feature with goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into a phased spec. - 100write-spec
Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document, scoping a feature with goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into a phased spec. - 100product-requirements
Write a product requirements document (PRD) that starts from the problem and its evidence, with measurable goals, non-goals, user stories with acceptance criteria, risks and how success is measured. Use it when the user wants to specify a feature, turn an idea into requirements or scope a project. - 90story-time
Start the Specify phase of the SPARK loop: the Product Owner interrogates a product idea and turns it into a spec with user stories and testable acceptance criteria. Use when the user brings a new feature idea, product idea or change request that has no spec yet — or wants an…