---
name: verification-before-completion
description: "Use before claiming work is complete, fixed, or passing, and before committing or creating PRs. Every completion claim must map to tool output produced in this session; for milestone-scale or multi-file work, dispatch a fresh-context verifier subagent instead of self-review."
---

# Verification Before Completion

## 边界声明

```
没有本会话的新鲜验证证据,就不得声称完成。
```

"应该可以了"、"看起来没问题"、"我有信心"都不是证据。证据 = 本会话中实际运行的命令及其输出。

## 证据化声明

最终报告里的每一条"已完成 / 已修复 / 已通过",都必须能对应到本会话的一次工具结果:

| 声明 | 所需证据 |
|---|---|
| 测试通过 | 本会话 `conda run -n PolyGateway pytest` 输出:0 failures |
| lint/格式干净 | `make lint` / `ruff check` 输出:0 errors |
| bug 已修复 | 复现原症状的测试:变更前失败、变更后通过(见 `test-driven-development` 结果门) |
| 需求已满足 | 对照 plan/spec 逐条核对的清单,每条指向 diff 或测试 |
| subagent 完成了任务 | 你亲自查看的 `git diff` / 文件内容,而非 subagent 的自述 |
| 无残留半成品 | grep TODO/NotImplementedError/占位 mock:0 命中;工作区无临时脚本与调试产物 |

无法出示证据的声明,改为陈述实际状态("X 已实现,Y 尚未验证,因为…")。

## 独立验证(里程碑级/多文件工作必做)

自我检查会继承自己的盲区。达到以下任一条件时,**必须派一个全新上下文的 verifier subagent**(只读)做独立核验,而不是自己过检查清单:

- 里程碑级任务或跨多文件的功能完成时;
- 提 PR / 合并回主线前;
- 执行完一份 plan 时。

做法:用 `Agent` 工具派一个 read-only subagent(如 `Explore` 或 general-purpose 限只读),prompt 只给它:任务需求原文(spec/plan 相关部分)、变更范围(分支/SHA 区间)、验证命令。**不给它你的实现思路与自评**——它的价值就在于没有你的上下文。要求它:

1. 亲自读 diff 与相关文件,逐条核对需求覆盖(缺失/多余/误解);
2. 亲自跑测试与 lint,报告真实输出;
3. 按 Critical/Important/Minor 返回问题清单。

对其结论逐条核验后修复;Critical/Important 未清零不得声称完成。小改动(单文件、明确修复)不必派 subagent,但证据化声明的要求不变。

## 留痕(`research-wiki/` 存在时)

验证**发现问题**时(全过则不写),记一条 finding:

```bash
.claude/tools/research_wiki.py add_entity research-wiki/ --type finding --id <slug> --title "<验证问题>"
.claude/tools/research_wiki.py rebuild_index research-wiki/
```

页内记录:验证命令、实际输出、失败原因、修复后结果。