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、范围、数据口径、接口契约、测试计划等）。 回写后必须提交 ：每次完成“用户回答 → 回写文档/联动更新”后，必须在本轮结束前做一次 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.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–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 题；其余留在文档并转为验证项/待办（可追溯）