From 39f2ac3c63eb23f6f4ffb622acb26ddc01a641f4 Mon Sep 17 00:00:00 2001 From: orize <12637585+orize@users.noreply.github.com> Date: Tue, 28 Jul 2026 22:58:12 +1000 Subject: [PATCH] clarify: require real interrogatives, ban topic-label questions (#3745) * 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 * Update templates/commands/clarify.md * 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 --------- Co-authored-by: Lorin O'Brien 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 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:** ?` 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