diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index fb0e91281f..ea2f20d519 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:** ?` or `**Question:** ? (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