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、范围、数据口径、接口契约、测试计划等）。
- 回写后必须提交：每次完成“用户回答 → 回写文档/联动更新”后，必须在本轮结束前做一次 git 提交，确保每轮澄清都有可追溯的提交点（提交信息必须使用中文）。
- 给定文件 ≠ 跳过门禁：如果用户给了文档路径，你可以跳过“全量扫描”，但只要该文件位于/可能位于
{FEATURE_DIR}下，仍必须先spec-context再读写。
选点顺序（先按 spec-pack 流程，从源头到下游）
第一优先级永远是“文档流程顺序”。因为前置文档的裁决会连锁影响后置文档，所以必须从源头开始调整：
- 先处理最靠前文档的未决点（例如先
requirements/raw.md，再solution.md，再prd.md…） - 只有当“前置文档的未决点清零 / 或已转成明确的验证项”后，才允许进入后置文档的澄清与回写
在同一份文档内部，才使用“高价值”规则决定先问哪一条：
- 阻断实现/验收：范围边界、入口流程、业务规则、AC、关键数据口径、权限模型
- 影响面大且不可逆：对外/跨模块契约、数据迁移/回滚、合规安全、删除策略
- 风险与成本：性能/容量/可靠性目标、灰度/发布/回滚策略、依赖与 SLA
- 可延期：文案、视觉细节、非关键配置（除非影响验收）
流程（按你给的步骤固化）
步骤 0：是否给定文件？
- “给定文件”仅指：用户提供了可定位的文档路径（例如
{FEATURE_DIR}/requirements/solution.md）。仅给片段/截图/口头描述不算给定文件。 - 若用户给定了文件路径：记录为
TARGET_DOC，直接进入 步骤 2（但仍需满足上面的门禁规则）。 - 若未给定文件：正在执行
spec-context获取上下文，并回显FEATURE_DIR=...，然后进入 步骤 1。
步骤 1：按 Spec Pack 流程顺序扫描（只扫描存在的文档）
按顺序扫描并提取“待澄清/待确认”的候选点：
requirements/raw.mdrequirements/solution.mdrequirements/prd.mdrequirements/prototype.mddesign/research.mddesign/design.mdimplementation/plan.mdverification/test-plan.mdverification/usecase.mdverification/suites.mdverification/report-*.md
扫描方法（合并去重）：
- 关键词信号：
待确认|待澄清|TBD|TODO|TBC|未定|暂定|暂不确定|后续再定|后续再议|Open Questions|FIXME|\?\?\? - 结构缺口信号：缺少范围边界/角色权限/数据口径/异常策略/验收口径/发布回滚/契约细节
输出一个列表（对话内维护即可）：
- 候选澄清点：按文档流程顺序分组与排列；每条包含「文件→章节→原文片段→为什么高价值（阻断/不可逆/风险）」；同一文件组内再按高价值排序
步骤 2：最小澄清循环（一次只问一个问题）
重复以下闭环：
- 从“候选澄清点”中选择 1 条最高优先级（先取最靠前文档的未决点；再在该文档内选最高价值）
- 把它改写成 1 个可裁决问题（2–4 个选项 + 推荐项 + 兜底）
- 等用户回答
- 立刻回写文档：把该点从“占位符/未定”改为“结论/规则/验收口径”，并同步更新受影响的其它文档段落
- 立刻 git 提交：只提交本轮澄清导致的相关文档变更；避免提交敏感文件（如
.env、凭据）。若没有实际文件变更则跳过提交。 - 从候选清单移除已解决项；若回写引入新不确定点，则加入候选清单
用户施压“别问了/一次问完/直接给默认值”时：仍然只问 1 个最高杠杆问题；其余未决项必须留在文档里，并转换为可执行验证项（而不是口头记账）。
步骤 3：回跳规则
- 若未给定文件：每解决 1–3 个问题后，回到 步骤 1 继续扫描（因为回写可能暴露新的缺口）。
- 若给定了文件：只在该文件及其直接相关文档范围内循环；当不确定点清零则结束。
回写最小格式（避免“口头结论”）
当你在文档中消除一个“待确认/TBD”点时，至少要把该处改成以下之一：
- 已裁决结论：明确写出规则/口径/权限/范围/AC（避免“暂定/后续再议”）
- 验证项（仍不确定时）：把它变成可执行验证条目（含：假设/风险 → 方法 → 成功/失败信号 → 触发动作），并明确“在进入实现/验收前必须完成”
并在必要时补 1 行“联动更新”提示：指出哪些章节/文档因为该裁决需要同步更新（例如 implementation/plan.md 的任务与验证步骤、verification/usecase.md 的用例与数据口径）。
Git 提交最小步骤（每轮澄清后执行一次）
- 检查变更：
git status；git diff - 暂存相关文件：
git add <本轮修改的文档路径...> - 提交（中文信息）：提交信息建议包含“澄清点 + 影响文档”，例如：
- 澄清：权限模型与数据口径 - 澄清：验收口径（更新 usecase 与 test-plan）
- 确认干净：
git status
快速参考
| 你看到的信号 | 你必须做什么 | 你绝不能做什么 |
|---|---|---|
| “TBD/待确认/未定” | 生成 1 个可裁决问题并只问这一题 | 直接补默认值当成结论写回 |
| 用户要你“一次问完” | 只问最高杠杆 1 题，其余转验证项 | 抛 20 个问题清单让用户疲劳回答 |
| 用户给了文件路径 | 直接聚焦该文档进入步骤 2 | 因为“有路径”就跳过门禁读写 |
红旗（出现任意一条 = 立刻停止并纠正）
- 未回显
FEATURE_DIR=...就开始读写 spec pack 文档 - 把“合理默认值”当“已确认结论”写进文档
- 前置文档未收敛就跳到后置文档修改/澄清（违反“从源头到下游”的顺序）
- 一次问多个问题/一次给用户多个裁决点
- 用户已回答但你没有立刻回写文档（只在对话里总结）
常见借口与反制（来自压测的典型失败）
| 借口（压力来源） | 常见违规行为 | 必须的反制动作 |
|---|---|---|
| “不要问我问题，直接给结果” | 直接把 TBD 补全成默认值写回 | 明确：需要裁决；只问 1 个最高杠杆问题并回写结论 |
| “一次性把问题都列出来” | 输出长清单、失去优先级与闭环 | 只问 1 题；其余留在文档并转为验证项/待办（可追溯） |