Skip to content

Specify Method

Jump to bottom
Gregor Biswanger edited this page Aug 3, 2026 · 1 revision

The Method Behind /sdd-specify

Background reference, not rules. The single source of the workflow is .claude/commands/sdd-specify.md — when this page and the command diverge, the command wins and this page gets fixed.

Adapted and translated from the German design document "Product Owner KI-Assistent — Adaptiver Spezifikations-Wizard für Spec-Driven Development" (v1.0), the interaction model the command grew from. Where FeatherSpec deliberately deviates from that original, the section Deliberate deviations says so and why.

Guiding idea

The assistant does not walk a big template. It knows every best-practice question and asks only the ones this particular idea needs. That keeps the product owner's time where it pays off — on intent, rules and acceptance, not on filling out forms — and yields a lean, testable specification that a developer or an AI coding agent can start from without unnecessary follow-up questions.

The interaction model

Phase Purpose
1. Understand the idea Recognize goal, product type, users, risk and complexity.
2. Build a relevance model Select only the question blocks this idea triggers.
3. Run the wizard interview One question at a time, with visible progress.
4. Maintain the running spec Structure every answer as it lands; mark assumptions.
5. Check the gaps Follow up on critical missing points only.
6. Write the spec file Persist to .specs/backlog/, lifecycle-ready.
7. Continue the loop /sdd-clarify attacks the spec, /sdd-plan derives the steps.

Principles carried through all phases — the command holds the binding wording:

  • One question per message. A batch gets skimmed and answered in bulk, which is the same as not asking.
  • Show progress ("Question X of Y") and adjust Y openly when new risk or complexity surfaces.
  • Never ask what the conversation, the repo or the Memory Bank already answers.
  • When a question looks demanding, say in half a sentence why it matters.
  • Thin answers are fine — offer a small choice instead of pressing.
  • Triage every gap: critical → ask now · important but not blocking → record as an assumption · optional → open point, or drop it.
  • Invent no facts. A guess presented as a decision is the failure mode this method exists to prevent.
  • "Done" from the user means: write the spec now, with what exists.

Question craft

The rationale behind the command's question bank: each always-relevant block exists because its absence breaks the spec — no problem means no good solution, unnamed users make acceptance untestable, a missing out-of-scope section reads as permission to build everything plausible. The conditional blocks (UI/UX, data, security, interfaces, compliance, performance, AI, operations, automation, reporting, brownfield) trigger on words in the idea, not on a fixed checklist, so a simple feature stays a short interview. The question budget (5–7 for a small change, up to 14–20 for a critical enterprise feature) is a promise of restraint the assistant makes before its first question.

Deliberate deviations from the original

The command keeps the interview and hardens the output. Each change closes a gap the chat-assistant format cannot close:

  • Repo grounding before asking. The original can only interview the product owner. The command first reads the Memory Bank, existing specs and — brownfield — the code, then interviews about the delta against the as-is. Questions get sharper because the repo has already answered some of them.
  • Five criterion shapes instead of Given/When/Then only. The original formats every acceptance criterion as Given/When/Then. Forcing an always-true invariant or a state-long rule into an event shape narrows it to one example — and the narrowed version is what gets built. Given/When/Then survives as an illustration under a criterion, never as its form.
  • A file, not a chat answer. The spec lands in .specs/backlog/NNNN-slug.md with a status line and stable AC- IDs, so /sdd-clarify, /sdd-plan and the traceability chain have something durable to hold on to.
  • Falsifiability is enforced, not requested. The vocabulary ban list, the "what observation would prove it false" test, "— because" on every exclusion, and the three-column assumptions register turn "make it testable" from an aspiration into a gate.

Sources

The original grounds the method in these; they remain good further reading:

FeatherSpec

Home ← Repository

Start here

Reference

Design & interop

Help

Clone this wiki locally