From 9d468951aeccf11965d9a5fe559e7394079788f6 Mon Sep 17 00:00:00 2001 From: Lorin O'Brien Date: Sun, 26 Jul 2026 14:04:07 +1000 Subject: [PATCH 1/3] clarify: require real interrogatives, ban topic-label questions Agents often present topic labels or bare requirement ids as "questions", which are not answerable on their own. Require a full interrogative under **Question:**, a plain-language stake sentence, then Recommended/options. Co-authored-by: Cursor --- templates/commands/clarify.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index fb0e91281f..ed8dd98278 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 sentence that ends with `?`. The question must stand 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. + - Put requirement / question ids only in trailing parentheses at the end of the question, never as the heading or 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 From c581b651e09c73f835ae5a5124483df3e93c58c4 Mon Sep 17 00:00:00 2001 From: orize <12637585+orize@users.noreply.github.com> Date: Tue, 28 Jul 2026 07:47:56 +1000 Subject: [PATCH 2/3] Update templates/commands/clarify.md --- templates/commands/clarify.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index ed8dd98278..b8014619a2 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -140,9 +140,9 @@ 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 sentence that ends with `?`. The question must stand on its own. + - Lead with `**Question:**` followed by a full interrogative sentence that ends with `?`. The question 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. - - Put requirement / question ids only in trailing parentheses at the end of the question, never as the heading or the whole prompt. + - Put requirement / question ids only in trailing parentheses at the end of the question, never as the whole heading or 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: From bc1660bd44ee95cc2f1033ee9728bf8996baa4fd Mon Sep 17 00:00:00 2001 From: Lorin O'Brien Date: Tue, 28 Jul 2026 19:08:10 +1000 Subject: [PATCH 3/3] clarify: allow requirement ids only after the ? Resolves Copilot feedback: an interrogative ending in ? cannot also have a parenthesized id "at the end of the question." Exact format is now `**Question:** ?` or `**Question:** ? (FR-023)`. Co-authored-by: Cursor --- templates/commands/clarify.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index b8014619a2..ea2f20d519 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -140,9 +140,9 @@ 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 sentence that ends with `?`. The question must make sense on its own. + - 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. - - Put requirement / question ids only in trailing parentheses at the end of the question, never as the whole heading or the whole prompt. + - 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: