交付前核验 · verification-before-completion

二次开发：本技能改编自 obra/superpowers 的 verification-before-completion（MIT © 2025 Jesse Vincent），在保留其核心方法论基础上，升级为「提示词 + 可执行 CLI」双形态。署名见本目录 NOTICE.md 与仓库 THIRD_PARTY_NOTICES.md。

这个技能做什么

交付（报告 / 周报 / 公文 / 代码 / 文案）发出前的自查门禁。

核心铁律一句话：没有新鲜的验证证据，不得声称完成。

• 你在这条消息里没有跑过验证动作，就不能声称"已通过 / 已搞定 / 没问题"。
• 违反字面规则 = 违反规则精神：换个说法、改个措辞、只验一半，都不算核验。

五步门控（在声称任何"完成 / 通过 / 搞定"之前，必须走完）：

1. 识别：这条声明需要什么证据才能站住？
2. 执行：跑完整的、新鲜的验证动作（不是以前跑过的那次）。
3. 读取：完整读输出，看退出码 / 看失败数 / 看关键数字。
4. 对照：输出是否真的支持这条声明？
   • 不支持 → 如实报告实际状态（带证据）。
   • 支持 → 带着证据下结论。
5. 才声称：走完前四步，才允许说"完成 / 通过"。

跳过任何一步 = 说谎，不是核验。

典型适用场景（中文职场高频）：

• 周报数据核实：周报里写的"Q3 营收增长 12%"——这个数是今天从报表里拉的，还是上周凭印象写的？
• 公文发出前核对：公文里的人名、职务、日期、文号——发出去之前逐条对着原件核过吗？
• 汇报材料自检：PPT 里的结论页，每一条都有本次验证过的数据撑腰吗？
• 交付前检查清单：代码交付、文档交付、方案交付——对照需求清单逐条打勾。
• 发布前门禁：上线 / 发版 / 提交 PR 之前，测试、构建、回归全跑过一遍了吗？

输入要求

• 必填：交付物的完整内容，或其中的声明 / 结论清单。
  • 交付物可以是：周报正文、公文草稿、汇报 PPT 文案、代码变更说明、方案文档等。
• 可选：每条声明对应的验证情况描述（用户自己说"这条我今天跑过测试了""那个数是上周一导的表"）。
  • 没有这部分也能跑——脚本会把所有缺验证信息的条目标为"待验证"。
• 信息不足时：不要替用户脑补"应该验过了"；一律标为"待验证"并给出具体验证动作建议。

输出结构（模板见 scripts/templates/verification-before-completion.template.md）

一份完整的核验报告，自上而下：

1. 标题：# 交付前核验报告 · {交付物主题}。
2. 声明核验清单（表格）：逐条列出交付物里的每条声明——声明内容 / 证据类型 / 证据是否新鲜（本次验证过？）/ 验证结果 / 结论（可声称 or 待验证）。
3. 未通过项与补救行动：每条待验证项给一个具体、可执行的验证动作建议（不是"再检查一下"这种废话，而是"今天从报表系统导出 Q3 营收数据，与周报数字核对"这种）。
4. 借口对照：把交付物里 / 用户自述中出现的"常见借口"映射到应做的动作（见下方对照表本地化）。
5. 最终结论：是否可交付 / 交付前必做清单（把所有"待验证"项列成 checklist，全部打勾后才能发）。

工作流程

1. 提取声明：通读交付物，把所有"声称性语句"摘出来——凡是断言某个事实、某个状态、某个结果的句子，都是一条待核验声明。
2. 判定证据类型：每条声明需要什么类型的证据（数据报表 / 测试输出 / 原文核对 / 构建退出码 / 需求清单逐条对照）。
3. 检查证据新鲜度：用户提供的验证情况里，哪些是本次刚验的，哪些是以前验过的——以前验过 ≠ 本次有效。
4. 对照门控五步：每条声明走一遍识别→执行→读取→对照→声称；缺哪步就标"待验证"。
5. 输出报告：按模板组装，未通过项给具体补救动作，末尾给最终交付结论。

质量规则（必须遵守）

• 忠实输出验证状态：绝不允许把"未验证"写成"已验证"，绝不允许把"待验证"包装成"基本没问题"。
• 证据新鲜度必须明示：每条声明都要写明"本次验证"还是"以前验证过"，两者不能混为一谈。
• 未验证项必须给可执行动作：不能只写"待验证"，必须给一条具体的、用户照着就能做的验证动作。
• 不替用户脑补：用户没说验过的，一律按"未验证"处理，不假设"应该验过了"。
• 红旗词敏感：交付物里出现"应该""大概""好像""差不多""之前跑过""应该没问题"这类措辞时，必须重点标注为待验证。
• 跳过步骤 = 说谎：五步门控缺任何一步，这条声明就不能标"可声称"。
• 直接输出 Markdown 正文，不要任何额外解释。

边界与异常处理

• 交付物很短、声明很少（≤3 条）→ 照样走完整流程，不因为条数少就跳过核验。
• 用户明确说"这条不用验" → 仍标注为"用户声明免验（未独立验证）"，不改成"可声称"。
• 声明涉及数字 / 金额 / 日期 / 人名 → 证据类型默认要求"本次从原始数据源核对"，不接受"凭记忆"。
• 代码类交付 → 证据类型默认要求"测试输出 0 失败 + 构建退出码 0"，linter 通过不算编译通过。
• 公文 / 正式函件 → 人名、职务、文号、日期必须逐条对照原件核验，不接受"大概是对的"。
• 中英混杂场景 → 保留英文技术术语，报告正文用中文。

与脚本配合

• 批量 / 命令行场景：scripts/draft_verification_before_completion.py（纯标准库，一条命令跑通）；输入为交付物内容或声明清单文本，输出为核验报告 Markdown。
• 自定义模板：复制 scripts/templates/verification-before-completion.template.md 修改后使用。