From 149baa27171d56f6a1c08f08e150d77710770ca6 Mon Sep 17 00:00:00 2001 From: Gyanu Mayank Date: Thu, 10 Sep 2026 17:18:54 +0530 Subject: [PATCH 1/2] Gate speckit.clarify so spec-taxonomy items are not deferred to plan The command treated "better deferred to planning" as a catch-all, so agents skipped NFRs, acceptance criteria, and edge cases. Spec hits must stay question candidates. Defer only implementation method, tech-stack comparison, or task breakdown. Fixes #1717 --- templates/commands/clarify.md | 22 +++++++++++++++++++++- tests/test_clarify_stage_gate.py | 18 ++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 tests/test_clarify_stage_gate.py diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 8663b6908b..2816f913d0 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -122,9 +122,25 @@ Execution steps: - TODO markers / unresolved decisions - Ambiguous adjectives ("robust", "intuitive") lacking quantification + Stage gate (spec vs plan). For every unchecked checklist item and every + Partial/Missing taxonomy category, classify before considering deferral: + 1. Match the item against the spec-oriented taxonomy above. + 2. A hit on any taxonomy category is a question candidate for THIS stage. + Do not defer NFRs, acceptance/DoD testability, edge cases, UX empty + states, domain constraints, or external-dependency failure modes. + 3. Defer to planning ONLY when the item is specifically about + implementation method, tech-stack comparison, or task breakdown. + 4. Mixed items (spec decision plus plan detail): split them and handle + the spec part now. + + If more than 60% of unresolved items would be marked Defer, pause, report + the ratio, and re-check each against the taxonomy before continuing. + For each category with Partial or Missing status, add a candidate question opportunity unless: - Clarification would not materially change implementation or validation strategy - - Information is better deferred to planning phase (note internally) + - The item failed the stage gate above (implementation method, tech-stack + comparison, or task breakdown). Note internally; do not use a vague + "better deferred to planning" catch-all. 4. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - Maximum of 5 total questions across the whole session. @@ -235,6 +251,10 @@ Behavior rules: - Respect user early termination signals ("stop", "done", "proceed"). - If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing. - If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale. +- MUST NOT defer spec-taxonomy items to Plan. Concurrent-user volume, NFR + quantification, acceptance-criteria testability, empty-state UX, and + external-dependency failure modes are spec questions. "How we implement + pagination" can wait; "whether the API paginates" cannot. Context for prioritization: {ARGS} diff --git a/tests/test_clarify_stage_gate.py b/tests/test_clarify_stage_gate.py new file mode 100644 index 0000000000..2259b0ead6 --- /dev/null +++ b/tests/test_clarify_stage_gate.py @@ -0,0 +1,18 @@ +"""Pin the spec-vs-plan stage gate in ``templates/commands/clarify.md`` (#1717). + +Agents were deferring NFRs, acceptance criteria, and edge cases to Plan +because the template allowed a vague "better deferred to planning" exit. +The gate must stay in the command the agent actually reads. +""" + +from pathlib import Path + +CLARIFY = Path(__file__).parent.parent / "templates" / "commands" / "clarify.md" + + +def test_clarify_has_spec_vs_plan_stage_gate() -> None: + text = CLARIFY.read_text(encoding="utf-8") + assert "Stage gate (spec vs plan)" in text + assert "implementation method, tech-stack comparison, or task breakdown" in text + assert "MUST NOT defer spec-taxonomy items to Plan" in text + assert "- Information is better deferred to planning phase (note internally)" not in text From 30b4cb9f0726ecc3d68b81481ccd7d5afd3730e6 Mon Sep 17 00:00:00 2001 From: Gyanu Mayank Date: Thu, 10 Sep 2026 22:15:42 +0530 Subject: [PATCH 2/2] Bound clarify planning deferral to implementation and tech-stack The unbounded "better deferred to planning" catch-all is gone. Spec taxonomy still lives in the command. Stage-gate procedure and defer-ratio audit belong in an opt-in wrap preset, not core. --- templates/commands/clarify.md | 22 +--------------------- tests/test_clarify_stage_gate.py | 17 +++++++++-------- 2 files changed, 10 insertions(+), 29 deletions(-) diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 2816f913d0..ea92264074 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -122,25 +122,9 @@ Execution steps: - TODO markers / unresolved decisions - Ambiguous adjectives ("robust", "intuitive") lacking quantification - Stage gate (spec vs plan). For every unchecked checklist item and every - Partial/Missing taxonomy category, classify before considering deferral: - 1. Match the item against the spec-oriented taxonomy above. - 2. A hit on any taxonomy category is a question candidate for THIS stage. - Do not defer NFRs, acceptance/DoD testability, edge cases, UX empty - states, domain constraints, or external-dependency failure modes. - 3. Defer to planning ONLY when the item is specifically about - implementation method, tech-stack comparison, or task breakdown. - 4. Mixed items (spec decision plus plan detail): split them and handle - the spec part now. - - If more than 60% of unresolved items would be marked Defer, pause, report - the ratio, and re-check each against the taxonomy before continuing. - For each category with Partial or Missing status, add a candidate question opportunity unless: - Clarification would not materially change implementation or validation strategy - - The item failed the stage gate above (implementation method, tech-stack - comparison, or task breakdown). Note internally; do not use a vague - "better deferred to planning" catch-all. + - The item is specifically about implementation method, tech-stack comparison, or task breakdown (note internally) 4. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - Maximum of 5 total questions across the whole session. @@ -251,10 +235,6 @@ Behavior rules: - Respect user early termination signals ("stop", "done", "proceed"). - If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing. - If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale. -- MUST NOT defer spec-taxonomy items to Plan. Concurrent-user volume, NFR - quantification, acceptance-criteria testability, empty-state UX, and - external-dependency failure modes are spec questions. "How we implement - pagination" can wait; "whether the API paginates" cannot. Context for prioritization: {ARGS} diff --git a/tests/test_clarify_stage_gate.py b/tests/test_clarify_stage_gate.py index 2259b0ead6..1c21ef9886 100644 --- a/tests/test_clarify_stage_gate.py +++ b/tests/test_clarify_stage_gate.py @@ -1,8 +1,8 @@ -"""Pin the spec-vs-plan stage gate in ``templates/commands/clarify.md`` (#1717). +"""The planning deferral in ``templates/commands/clarify.md`` must stay bounded (#1717). -Agents were deferring NFRs, acceptance criteria, and edge cases to Plan -because the template allowed a vague "better deferred to planning" exit. -The gate must stay in the command the agent actually reads. +The old catch-all ("Information is better deferred to planning phase") let +agents skip NFRs, acceptance criteria, and edge cases. Defer only +implementation method, tech-stack comparison, or task breakdown. """ from pathlib import Path @@ -10,9 +10,10 @@ CLARIFY = Path(__file__).parent.parent / "templates" / "commands" / "clarify.md" -def test_clarify_has_spec_vs_plan_stage_gate() -> None: +def test_clarify_planning_deferral_is_bounded() -> None: text = CLARIFY.read_text(encoding="utf-8") - assert "Stage gate (spec vs plan)" in text - assert "implementation method, tech-stack comparison, or task breakdown" in text - assert "MUST NOT defer spec-taxonomy items to Plan" in text assert "- Information is better deferred to planning phase (note internally)" not in text + assert ( + "implementation method, tech-stack comparison, or task breakdown" + in text + )