Bug: /speckit.clarify 在 spec 阶段将 spec 级别条目错误 defer 到 plan

[bigsmartben]

问题描述

/speckit.clarify 在 checklist 驱动模式（checklists/spec-quality.md）下，将 24 个未勾选条目全部标记为"Plan 阶段关注"并 defer，跳过了 spec 阶段应承担的澄清职责。Agent 同时输出了自相矛盾的结论："No critical ambiguities detected"，但实际上存在大量未解决的 spec 级别模糊项。

复现步骤

/speckit.clarify checklists/spec-quality.md

Agent 输出大量 remaining 条目，将其全部归类为 Plan-stage concerns，未向用户提出任何 spec 级别的澄清问题。

被错误 defer 的条目分析

按 clarify.md 规范的 spec-oriented taxonomy，以下条目应在 spec 阶段澄清，而非 defer：

条目	被错误标记为	实际所属 spec taxonomy 分类
CHK014 并发用户量	Plan: 容量规划	Non-Functional Quality Attributes
CHK032-036 NFR 细化	Plan: 运维设计	Non-Functional Quality Attributes
CHK020-022 验收量化	Plan: 测试策略	Completion Signals
CHK025, CHK028-031 边界与异常	Plan: 集成/容错设计	Edge Cases & Failure Handling
CHK004 图片约束	Plan: 存储方案设计	Domain & Data Model / Constraints
CHK008 空状态	Plan: 标准 UX 模式	Interaction & UX Flow
CHK037-040 依赖契约	Plan: 契约冻结	Integration & External Dependencies
CHK001, CHK007 API 分页	Plan: 接口设计	边界（"是否需要分页"属 spec，"实现方式"属 plan）

根因分析

Agent 缺乏阶段归属判断机制——在决定"某条目是否 defer 到下游"时，未对照 clarify.md 中定义的 spec-oriented taxonomy 进行分类匹配，而是基于条目关键词做了粗粒度的直觉判断，导致"懒惰 defer"。

建议优化方向

1. 在 Step 2 与 Step 3 之间插入 Stage Gate 判断步骤

对于每个未勾选的 checklist 条目：
1. 将条目内容与当前阶段 taxonomy 分类做逐项匹配
2. 命中任一 taxonomy 分类 → 标记为"本阶段可澄清"
3. 仅当条目明确涉及"实现方式选择"、"技术方案对比"、"任务分解"等
   plan/implement 特有关注点时 → 方可标记为"Defer to Plan"
4. 边界案例：条目同时涉及 spec 和 plan → 拆分后优先按 spec 处理

2. 增加 Defer 比例上限告警

如果单次执行中 Defer 条目占比 > 60%，agent 必须暂停并输出：
"⚠️ 大量条目被标记为 Defer（{N}/{Total}）。正在重新校验阶段归属..."
然后重新对照 taxonomy 逐条复核。

3. 在 Behavior Rules 中补充反例

## 反例（MUST NOT）
- ❌ 将"并发用户量"defer 到 Plan —— NFR 量化指标属 spec
- ❌ 将"验收标准可测试性"defer 到 Plan —— Completion Signals 属 spec
- ❌ 将"空状态 UX"defer 到 Plan —— Interaction & UX Flow 属 spec
- ❌ 将"外部依赖失败模式"defer 到 Plan —— Integration & External Dependencies 属 spec

影响范围

• templates/commands/clarify.md（Step 3 问题生成逻辑 + Behavior Rules）
• tests/test_agent_command_consistency.py（可新增 taxonomy 阶段归属覆盖测试）

优先级

High — 该问题导致 spec 阶段产出文档质量不足，将本应在 spec 阶段解决的模糊性带入 plan，增加下游返工成本。

[dhilipkumars]

LLM Translation @bigsmartben is this correct?

Issue Description

When running /speckit.clarify in checklist-driven mode (checklists/spec-quality.md), the Agent marks all 24 unchecked items as "Plan-stage concerns" and defers them, completely skipping the clarification responsibilities it should fulfill during the spec stage. The Agent also outputs a contradictory conclusion: "No critical ambiguities detected", even though there are actually numerous unresolved spec-level ambiguities.

Steps to Reproduce

1. Run /speckit.clarify checklists/spec-quality.md
2. Observation: The Agent outputs a large number of remaining items, categorizing all of them as Plan-stage concerns without asking the user any spec-level clarification questions.

Analysis of Incorrectly Deferred Items

According to the spec-oriented taxonomy defined in clarify.md, the following items should be clarified during the spec stage rather than being deferred:

Item	Incorrectly Tagged As	Actual Spec Taxonomy Classification
CHK014 Concurrent user volume	Plan: Capacity planning	Non-Functional Quality Attributes
CHK032-036 NFR refinement	Plan: Operations design	Non-Functional Quality Attributes
CHK020-022 Acceptance quantification	Plan: Testing strategy	Completion Signals
CHK025, CHK028-031 Boundaries & exceptions	Plan: Integration/Fault tolerance design	Edge Cases & Failure Handling
CHK004 Image constraints	Plan: Storage solution design	Domain & Data Model / Constraints
CHK008 Empty states	Plan: Standard UX patterns	Interaction & UX Flow
CHK037-040 Dependency contracts	Plan: Contract freezing	Integration & External Dependencies
CHK001, CHK007 API pagination	Plan: Interface design	Boundaries ("Whether pagination is needed" is spec, "How to implement it" is plan)

Root Cause Analysis

The Agent lacks a stage-attribution judgment mechanism. When deciding whether to "defer an item downstream," it fails to map the item against the spec-oriented taxonomy defined in clarify.md. Instead, it makes coarse-grained, intuitive judgments based on item keywords, resulting in "lazy deferrals."

Proposed Optimizations

1. Insert a Stage Gate judgment step between Step 2 and Step 3
For each unchecked checklist item:

1. Match the item content item-by-item against the current stage's taxonomy classifications.
2. If it matches any taxonomy classification → mark as "Clarifiable in the current stage".
3. Only when the item explicitly involves plan/implement-specific concerns (e.g., "implementation method selection", "technical solution comparison", "task breakdown") → mark as "Defer to Plan".
4. Edge cases: If an item involves both spec and plan → split it and prioritize processing the spec portion.

2. Add a Defer Ratio Upper Limit Alert
If the proportion of deferred items in a single execution > 60%, the agent must pause and output:

"⚠️ A large number of items have been marked as Defer ({N}/{Total}). Re-verifying stage attribution..."

The Agent should then re-verify each item against the taxonomy.

3. Supplement Anti-patterns in Behavior Rules
Add the following to the MUST NOT section:

• ❌ Deferring "concurrent user volume" to Plan — Quantified NFR metrics belong to the spec stage.
• ❌ Deferring "acceptance criteria testability" to Plan — Completion Signals belong to the spec stage.
• ❌ Deferring "empty state UX" to Plan — Interaction & UX Flow belongs to the spec stage.
• ❌ Deferring "external dependency failure modes" to Plan — Integration & External Dependencies belong to the spec stage.

Impact Scope

• templates/commands/clarify.md (Step 3 question generation logic + Behavior Rules)
• tests/test_agent_command_consistency.py (Add taxonomy stage attribution coverage tests)

Priority

High — This issue results in poor document quality during the spec phase. It carries ambiguities that should be resolved in the spec stage over to the plan stage, significantly increasing downstream rework costs.