Spec Checklist

spec-checklist（Spec Pack 文档待澄清点扫描与收敛）

概述

本技能用于在当前 Spec Pack 内按流程顺序扫描文档，找出“待澄清/待确认”的高价值问题，并通过一次只问一个问题的循环把结论回写到对应文档，直到不确定性被消除或被转成可验证条目。

核心原则：不猜、不批量问、不留口头结论；每次裁决后立刻落盘。

何时使用

• 你看到 spec pack 文档中出现 待确认/待澄清/TBD/TODO/未定/暂定/Open Questions/???/FIXME 等
• 你不确定某段文本是“结论”还是“占位符/假设/口头约定”
• 你需要把不确定性收敛为：已确认结论 或 可执行验证项

硬规则（必须遵守）

• 门禁优先：只要要读写 {FEATURE_DIR}/requirements|design|implementation|verification，必须先执行 REQUIRED SUB-SKILL：spec-context 获取上下文，并在对话中回显 FEATURE_DIR=...（允许 (reuse)）。
• spec-context 失败就停止：若无法得到有效 FEATURE_DIR=...，必须立刻停止；只输出“阻断原因 + 需要的最小输入”（例如：切到正确 spec 分支、或提供实际存在且含 requirements/ 的 FEATURE_DIR）。
• 禁止猜测/默认值冒充结论：看到 TBD/待确认时，除非用户已明确裁决，否则不得把它“补全成合理默认值”并写入文档。
• 一次只问一个问题：每轮只提出 1 个最高杠杆澄清问题（2–4 个选项 + 推荐项 + 兜底“其他/不确定”）。
• 问完就回写：用户回答后，必须立刻更新对应文档（消除占位符），并在需要时联动更新相关文档（例如 AC、范围、数据口径、接口契约、测试计划等）。
• 回写后必须提交（受 AUTO_COMMIT 控制）：每次完成"用户回答 → 回写文档/联动更新"后：
  • AUTO_COMMIT=true（默认）：必须在本轮结束前做一次 git 提交，确保每轮澄清都有可追溯的提交点（提交信息必须使用中文）。
  • AUTO_COMMIT=false：跳过 git add + git commit，改为输出"已变更文件清单，请手动提交"并列出本轮修改的文件路径。
• 给定文件 ≠ 跳过门禁：如果用户给了文档路径，你可以跳过“全量扫描”，但只要该文件位于/可能位于 {FEATURE_DIR} 下，仍必须先 spec-context 再读写。

选点顺序（先按 spec-pack 流程，从源头到下游）

**第一优先级永远是“文档流程顺序”。**因为前置文档的裁决会连锁影响后置文档，所以必须从源头开始调整：

1. 先处理最靠前文档的未决点（例如先 requirements/raw.md，再 solution.md，再 prd.md …）
2. 只有当“前置文档的未决点清零 / 或已转成明确的验证项”后，才允许进入后置文档的澄清与回写

在同一份文档内部，才使用“高价值”规则决定先问哪一条：

• 阻断实现/验收：范围边界、入口流程、业务规则、AC、关键数据口径、权限模型
• 影响面大且不可逆：对外/跨模块契约、数据迁移/回滚、合规安全、删除策略
• 风险与成本：性能/容量/可靠性目标、灰度/发布/回滚策略、依赖与 SLA
• 可延期：文案、视觉细节、非关键配置（除非影响验收）

流程（按你给的步骤固化）

步骤 0：是否给定文件？

• “给定文件”仅指：用户提供了可定位的文档路径（例如 {FEATURE_DIR}/requirements/solution.md）。仅给片段/截图/口头描述不算给定文件。
• 若用户给定了文件路径：记录为 TARGET_DOC，直接进入 步骤 2（但仍需满足上面的门禁规则）。
• 若未给定文件：正在执行 spec-context 获取上下文，并回显 FEATURE_DIR=...，然后进入 步骤 1。

步骤 1：按 Spec Pack 流程顺序扫描（只扫描存在的文档）

按顺序扫描并提取“待澄清/待确认”的候选点：

• requirements/raw.md
• requirements/solution.md
• requirements/prd.md
• requirements/prototype.md
• design/research.md
• design/design.md
• implementation/plan.md
• verification/test-plan.md
• verification/usecase.md
• verification/suites.md
• verification/report-*.md

扫描方法（合并去重）：

• 关键词信号：待确认|待澄清|TBD|TODO|TBC|未定|暂定|暂不确定|后续再定|后续再议|Open Questions|FIXME|\?\?\?
• 结构缺口信号：缺少范围边界/角色权限/数据口径/异常策略/验收口径/发布回滚/契约细节

输出一个列表（对话内维护即可）：

• 候选澄清点：按文档流程顺序分组与排列；每条包含「文件→章节→原文片段→为什么高价值（阻断/不可逆/风险）」；同一文件组内再按高价值排序

步骤 2：最小澄清循环（一次只问一个问题）

重复以下闭环：

1. 从“候选澄清点”中选择 1 条最高优先级（先取最靠前文档的未决点；再在该文档内选最高价值）
2. 把它改写成 1 个可裁决问题（2–4 个选项 + 推荐项 + 兜底）
3. 等用户回答
4. 立刻回写文档：把该点从“占位符/未定”改为“结论/规则/验收口径”，并同步更新受影响的其它文档段落
5. 立刻 git 提交（受 AUTO_COMMIT 控制）：
   • AUTO_COMMIT=true（默认）：只提交本轮澄清导致的相关文档变更；避免提交敏感文件（如 .env、凭据）。若没有实际文件变更则跳过提交。
   • AUTO_COMMIT=false：跳过提交，输出"以下文件已变更，请手动提交："并列出本轮修改的文件路径。
6. 从候选清单移除已解决项；若回写引入新不确定点，则加入候选清单

用户施压“别问了/一次问完/直接给默认值”时：仍然只问 1 个最高杠杆问题；其余未决项必须留在文档里，并转换为可执行验证项（而不是口头记账）。

步骤 3：回跳规则

• 若未给定文件：每解决 1–3 个问题后，回到 步骤 1 继续扫描（因为回写可能暴露新的缺口）。
• 若给定了文件：只在该文件及其直接相关文档范围内循环；当不确定点清零则结束。

回写最小格式（避免“口头结论”）

当你在文档中消除一个“待确认/TBD”点时，至少要把该处改成以下之一：

• 已裁决结论：明确写出规则/口径/权限/范围/AC（避免“暂定/后续再议”）
• 验证项（仍不确定时）：把它变成可执行验证条目（含：假设/风险 → 方法 → 成功/失败信号 → 触发动作），并明确“在进入实现/验收前必须完成”

并在必要时补 1 行“联动更新”提示：指出哪些章节/文档因为该裁决需要同步更新（例如 implementation/plan.md 的任务与验证步骤、verification/usecase.md 的用例与数据口径）。

Git 提交最小步骤（每轮澄清后执行一次，受 AUTO_COMMIT 控制）

当 AUTO_COMMIT=true（默认）时：

• 检查变更：git status；git diff
• 暂存相关文件：git add <本轮修改的文档路径...>
• 提交（中文信息）：提交信息建议包含"澄清点 + 影响文档"，例如：
  • 澄清：权限模型与数据口径
  • 澄清：验收口径（更新 usecase 与 test-plan）
• 确认干净：git status

当 AUTO_COMMIT=false 时：

• 跳过 git add + git commit
• 输出"以下文件已变更，请手动提交："并列出本轮修改的文件路径
• 继续进入下一轮澄清循环（不因跳过提交而中断流程）

快速参考

红旗（出现任意一条 = 立刻停止并纠正）

• 未回显 FEATURE_DIR=... 就开始读写 spec pack 文档
• 把“合理默认值”当“已确认结论”写进文档
• 前置文档未收敛就跳到后置文档修改/澄清（违反“从源头到下游”的顺序）
• 一次问多个问题/一次给用户多个裁决点
• 用户已回答但你没有立刻回写文档（只在对话里总结）

常见借口与反制（来自压测的典型失败）