在 Spec Kit 功能规格存在未明确决策点时，用最多…

适用于已有 Spec Kit 功能规格、但行为/数据/交互/非功能/边界等仍有歧义，需要在计划前澄清并同步更新 spec 的场景。

适用场景

解决思路

1. 开始前读取非空 `$ARGUMENTS`，并在后续澄清流程中必须考虑它。
2. 澄清前检查项目根目录是否存在 `.specify/extensions.yml`；若存在则读取并查找 `hooks.before_clarify` 下条目；若不存在或无 hooks 注册则静默跳过。
3. 若 `.specify/extensions.yml` 无法解析或无效，不要静默跳过：告诉用户该文件无法读取（包含 parser error），未检查任何 hooks（包括 mandatory `optional: false` hooks），然后继续正常流程。
4. 过滤 `hooks.before_clarify` 中 `enabled` 明确为 `false` 的 hook；无 `enabled` 字段默认视为启用。
5. 对剩余 hook 不要解释或评估 `condition`：无 `condition`、null 或空值视为可执行；有非空 `condition` 则跳过，把条件评估留给 HookExecutor 实现。
6. 构造 hook 命令调用时，将 command name 中的点 `.` 替换为连字符 `-`，例如 `speckit.git.commit` → `/speckit-git-commit`。
7. 对可执行前置 hook 按 `optional` 输出：`optional: true` 输出 Extension Hooks 块（含 extension、command、description、prompt、To execute）；`optional: false` 输出 Automatic Pre-Hook 块（含 extension、Executing、`EXECUTE_COMMAND: {command}`），且必须实际调用 hook 并等待完成后再进入 Outline；运行方式可为 `/skill:speckit-...` 或 `$speckit-...`。
8. 澄清总目标：检测并减少当前 feature spec 中的歧义或缺失决策点，并直接把澄清记录到 spec 文件。
9. 注意澄清工作流应在调用 `/speckit-plan` 前运行并完成；若用户明确跳过澄清（如探索性 spike），可继续，但必须警告下游返工风险增加。
10. 从 repo root 运行一次 `.specify/scripts/bash/check-prerequisites.sh --json --paths-only`（组合 `--json --paths-only` / `-Json -PathsOnly`）。
11. 解析该命令的最小 JSON payload 字段：`FEATURE_DIR`、`FEATURE_SPEC`；可选捕获 `IMPL_PLAN`、`TASKS` 供未来链式流程。
12. 若 JSON 解析失败，中止并让用户重新运行 `/speckit-specify` 或验证 feature branch 环境。
13. 对于 args 中单引号如「I'm Groot」，使用转义语法 `'I'\''m Groot'`，或改用双引号 `"I'm Groot"`。
14. 如果存在 `.specify/memory/constitution.md`，加载它获取项目原则和治理约束。
15. 加载当前 spec 文件，并按 taxonomy 做结构化歧义与覆盖扫描；每个类别标记 `Clear` / `Partial` / `Missing`，生成内部 coverage map 用于优先级排序（若不会提问则不要输出原始 map）。
16. Functional Scope & Behavior 扫描：核心用户目标与成功标准；显式 out-of-scope 声明；用户角色 / personas 区分。
17. Domain & Data Model 扫描：实体、属性、关系；身份与唯一性规则；生命周期 / 状态转换；数据量 / 规模假设。
18. Interaction & UX Flow 扫描：关键用户旅程 / 序列；错误 / 空 / 加载状态；可访问性或本地化说明。
19. Non-Functional Quality Attributes 扫描：性能（延迟、吞吐目标）；可扩展性（水平/垂直、限制）；可靠性与可用性（uptime、恢复期望）；可观测性（日志、指标、追踪信号）；安全与隐私（authN/Z、数据保护、威胁假设）；合规 / 监管约束（若有）。
20. Integration & External Dependencies 扫描：外部服务 / API 及失败模式；数据导入 / 导出格式；协议 / 版本假设。
21. Edge Cases & Failure Handling 扫描：负面场景；限流 / 节流；冲突解决（如并发编辑）。
22. Constraints & Tradeoffs 扫描：技术约束（语言、存储、托管）；显式权衡或被拒绝的替代方案。
23. Terminology & Consistency 扫描：规范术语表；避免的同义词 / 弃用术语。
24. Completion Signals 扫描：验收标准可测试性；可衡量的 Definition of Done 风格指标。
25. Misc / Placeholders 扫描：TODO 标记 / 未解决决策；缺乏量化的模糊形容词（如 robust、intuitive）。
26. 对每个 `Partial` 或 `Missing` 类别添加候选问题机会，除非：澄清不会实质改变实现或验证策略；或该项专门关于实现方法、技术栈比较、任务拆解（在内部记录）。
27. 内部生成按优先级排序的候选澄清问题队列，最多 5 个；不要一次全部输出。
28. 整个会话最多问 5 个问题。
29. 每个问题必须能用短多选（2–5 个不同且互斥选项）回答，或一词 / 短语答案回答，并明确限制「Answer in <=5 words」。
30. 只包含答案会实质影响架构、数据建模、任务拆解、测试设计、UX 行为、运维就绪或合规验证的问题。
31. 确保类别覆盖平衡：先覆盖最高影响未解决类别；避免在高影响领域（如安全态势）未解决时问两个低影响问题。
32. 排除已回答、琐碎风格偏好或计划级执行细节（除非阻塞正确性）。
33. 优先选择能减少下游返工风险或防止验收测试错位的澄清。
34. 若超过 5 个类别未解决，按 (Impact * Uncertainty) 启发式选择前 5 个。
35. 顺序提问循环中一次只展示恰好一个问题。
36. 问题写作质量：以 `**Question:**` 开头，后跟完整疑问句并以 `?` 结尾；`?` 前文本必须能独立理解。
37. 绝不用主题标签、章节标题或 requirement id 作为问题本身；例如 `Acceptance device/runtime matrix (FR-023)` 无效。
38. `?` 后唯一允许后缀是可选括号内的 requirement/question id：格式 `**Question:** <interrogative>?` 或 `**Question:** <interrogative>? (FR-023)`；id 不得在 `?` 前，也不得单独或加主题标签作为整个提示。
39. 问题行后立即添加一句通俗的「Why it matters」（说明对验收或发布的风险），然后才给推荐 / 选项。
40. 使用日常措辞；只有同句定义时才引入术语；自检：不懂 Spec Kit 的读者必须能仅凭 Question 行回答；简洁可以，隐晦标签不行。
41. 多选问题：分析所有选项，基于项目类型最佳实践、类似实现常见模式、风险降低（安全、性能、可维护性）、与 spec 中明确目标 / 约束对齐，确定最合适选项。
42. 多选问题：在顶部显眼展示推荐，格式 `**Recommended:** Option [X] - <reasoning>`，理由 1–2 句。
43. 多选问题：用 Markdown 表格渲染所有选项（Option / Description），必要时添加 D/E 最多到 5，以及 `Short` 自由短答选项（<=5 words，若适合）。
44. 多选问题：表格后添加：`You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
45. 短答问题：基于最佳实践和上下文提供建议答案，格式 `**Suggested:** <your proposed answer> - <brief reasoning>`。
46. 短答问题：输出 `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
47. 用户回答后：若回复 `yes`、`recommended` 或 `suggested`，使用此前推荐 / 建议作为答案。
48. 否则验证答案映射到一个选项或符合 <=5 词约束。
49. 若答案歧义，快速请求消歧（仍算同一问题，不推进）。
50. 满意后记录到工作内存（尚不写磁盘），进入下一排队问题。
51. 停止提问条件：所有关键歧义提前解决（剩余排队不必要）、用户信号完成（`done`、`good`、`no more`）、或达到 5 个问题。
52. 永不提前透露未来排队问题。
53. 若开始时无有效问题，立即报告无关键歧义。
54. 每个接受的答案后增量集成：维护内存中的 spec 表示（开始时加载一次）加原始文件内容。
55. 本会话第一个集成答案：确保存在 `## Clarifications` 部分；若缺失，按 spec 模板创建在最高层上下文 / 概览部分之后。
56. 在 `## Clarifications` 下创建（若不存在）`### Session YYYY-MM-DD` 子标题为今天。
57. 接受后立即追加 bullet：`- Q: <question> → A: <final answer>`。
58. 然后立即将澄清应用到最合适部分：功能歧义 → 更新或添加 Functional Requirements bullet。
59. 用户交互 / actor 区分 → 更新 User Stories 或 Actors 子节（若存在），澄清 role、constraint、scenario。
60. 数据形状 / 实体 → 更新 Data Model（添加字段、类型、关系），保持顺序；简洁注明新增约束。
61. 非功能约束 → 在 Success Criteria > Measurable Outcomes 添加 / 修改可衡量标准，将模糊形容词转为 metric 或 explicit target。
62. 边缘情况 / 负面流程 → 在 Edge Cases / Error Handling 下添加新 bullet（或创建该子节，若模板有占位）。
63. 术语冲突 → 跨 spec 规范化术语；必要时保留原始，仅一次添加 `(formerly referred to as "X")`。
64. 若澄清使早先模糊陈述无效，替换该陈述而非重复；不留过时矛盾文本。
65. 每次集成后保存 spec 文件（原子覆盖），以减少上下文丢失风险。
66. 保持格式：不重排无关部分；保持 heading hierarchy 完整。
67. 保持每个插入澄清最小且可测试，避免叙事漂移。
68. 验证（每次写入后加最终通过）：Clarifications session 每个接受答案恰好一条 bullet，无重复。
69. 验证：总提问（接受）问题 ≤ 5。
70. 验证：更新部分无残留模糊占位符（新答案意在解决的）。
71. 验证：无早先矛盾陈述残留；扫描并移除现已无效的替代选择。
72. 验证：Markdown 结构有效；仅允许新 headings：`## Clarifications`、`### Session YYYY-MM-DD`。
73. 验证：术语一致性：所有更新部分使用同一 canonical term。
74. 将更新后的 spec 写回 `FEATURE_SPEC`。
75. 重新验证 Spec Quality Checklist：检查 `FEATURE_DIR/checklists/requirements.md` 是否存在；若不存在静默跳过。
76. 若 checklist 存在：读取该文件。
77. 识别所有 GitHub task-list checkbox 行：匹配 `- [ ]`、`- [x]`、`- [X]`（大小写不敏感，容忍嵌套项前导空白），在代码围栏之外；忽略其他内容（标题、注释、非 checkbox bullet、metadata）。
78. 对每个 checkbox 行记录当前 marker 状态和 item text 到 before-snapshot 列表。
79. 针对更新后的 spec（step 7 保存版本）重新评估每个 checkbox 项。
80. 对每个 checkbox 项，仅当 checked/unchecked 状态实际变化时更新：现在通过且未勾选 → `[ ]` 改 `[x]`；现在失败且已勾选 → `[x]`/`[X]` 改 `[ ]`；未变则保持 marker 原样（保留现有大小写避免外观 diff）。
81. 保存更新后的 checklist 文件。只切换状态变化的 checkbox 行的 `[ ]`/`[x]` marker 部分；其他内容（标题、metadata、注释、行序、空白）保持不变以避免噪声 diff。
82. 比较 before-snapshot 与当前状态，计算三列表：Newly passing、Regressions、Still unchecked。
83. 记录 before/after pass counts as checked/total checkbox items（如 `12/16 → 15/16 items passing`）。
84. 行为规则：若未发现有意义歧义或所有潜在问题低影响，回复 `No critical ambiguities detected worth formal clarification.` 并建议继续。
85. 行为规则：若 spec 文件缺失，让用户先运行 `/speckit-specify`；不要在此创建新 spec。
86. 行为规则：永不超过 5 个总提问数；单个问题的澄清重试不算新问题。
87. 行为规则：避免推测性 tech stack 问题，除非缺失会阻塞功能清晰性。
88. 行为规则：尊重用户提前终止信号（`stop`、`done`、`proceed`）。
89. 行为规则：若因全覆盖未提问，输出紧凑 coverage summary（所有类别 `Clear`），然后建议推进。
90. 行为规则：若配额达到但仍有未解决高影响类别，明确在 Deferred 下标记并给理由。
91. 行为规则：用 `$ARGUMENTS` 作为优先级排序上下文。
92. 强制后置执行钩子：完成前检查 `.specify/extensions.yml` 是否存在；若不存在或 `hooks.after_clarify` 无注册，跳到 Completion Report。
93. 若存在，读取并查找 `hooks.after_clarify` 下条目。
94. 若后置 YAML 无法解析或无效，不静默跳过：告知用户无法读取（包含 parser error），未检查 hooks（包括 mandatory `optional: false` 的），然后继续 Completion Report。
95. 后置钩子同样过滤 `enabled` 明确为 `false` 的 hook；无 `enabled` 默认启用。
96. 后置钩子同样不要解释 / 评估 `condition`：无 `condition` 或 null/empty 可执行；有非空 `condition` 则跳过，交给 HookExecutor 实现。
97. 构造后置命令调用时将 hook command name 中的点替换为连字符，例如 `speckit.git.commit` → `/speckit-git-commit`。
98. 对可执行后置 hook：`optional: false` 必须输出 `## Extension Hooks` 块，含 `**Automatic Hook**: {extension}`、`Executing: `/{command}``、`EXECUTE_COMMAND: {command}`，并实际调用等待完成；`optional: true` 输出含 extension、command、description、prompt、To execute 的块。
99. Completion Report：报告完成（提问循环结束或提前终止）时包含提问并回答数量。
100. Completion Report：包含更新 spec 路径。
101. Completion Report：包含触及 sections 列表。
102. Completion Report：Spec quality checklist 状态（若重新验证）：显示 before/after 通过数（如 `12/16 → 15/16 items passing`），列出状态变化项（新勾选和回归）；若有未勾选项列为需关注领域。
103. Completion Report：Coverage summary 表，每个 taxonomy 类别状态：Resolved（之前 Partial/Missing 且已处理）、Deferred（超出问题配额，或剩余项专门是实现方法、技术栈比较、任务拆解）、Clear（已充分）、Outstanding（仍 Partial/Missing 但低影响）。
104. Completion Report：若存在 Outstanding 或 Deferred，建议继续 `/speckit-plan` 还是稍后 post-plan 再运行 `/speckit-clarify`。
105. Completion Report：建议下一步命令。
106. Done When：spec 歧义已识别且澄清集成到 spec 文件。
107. Done When：spec quality checklist 已针对更新 spec 重新验证（若 `FEATURE_DIR/checklists/requirements.md` 存在）。
108. Done When：Extension hooks 已根据 Mandatory Post-Execution Hooks 规则分派或跳过。
109. Done When：向用户报告完成，含问题数、触及 sections、checklist 状态、coverage summary。

适用边界 · 注意事项

• 项目不是 spec-kit 结构、缺少 `.specify/` 目录，或当前没有功能 spec 文件。
• 用户明确表示跳过澄清，或处于探索性 spike 阶段；继续会保留但需警告下游返工风险增加。
• 规格已完全清晰、没有关键歧义，或问题只涉及实现方法、技术栈比较、任务拆解等低影响事项。