Skip to content

💫 Toolkit to help you get started with SDD or any other process!

clarify: require real interrogatives, ban topic-label questions (#3745)

orize39f2ac3c63eb
diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md
index fb0e91281..ea2f20d51 100644
--- a/templates/commands/clarify.md
+++ b/templates/commands/clarify.md
@@ -139,6 +139,12 @@ Execution steps:
5. Sequential questioning loop (interactive):
- Present EXACTLY ONE question at a time.
+ - **Question writing quality (applies to every question, MC or short-answer):**
+ - Lead with `**Question:**` followed by a full interrogative that ends with `?`. The question text before the `?` must make sense on its own.
+ - NEVER use a topic label, section heading, or requirement id as the question itself. For example, `Acceptance device/runtime matrix (FR-023)` is INVALID — it is a label, not a question.
+ - After the `?`, the only permitted suffix is an optional parenthesized requirement/question id. Exact format: `**Question:** <interrogative>?` or `**Question:** <interrogative>? (FR-023)`. Never put the id before the `?`, and never use the id (alone or with a topic label) as the whole prompt.
+ - Immediately after the question line, add one plain-language "Why it matters" sentence (the stake for acceptance or shipping) before the recommendation/options.
+ - Use everyday wording; introduce jargon only if defined in the same sentence. Self-check: a reader who does not know Spec Kit must be able to answer from the Question line alone. Terse is fine; cryptic labels are not.
- For multiple‑choice questions:
- **Analyze all options** and determine the **most suitable option** based on:
- Best practices for the project type