feature-completion-audit

name	feature-completion-audit
description	对照原始需求，客观判断一项功能是否真正实现完成。从需求覆盖、验收对齐、正确性边界、契约集成、测试证据、范围偏离六个维度独立取证，输出可追溯的完成度结论与缺口清单。两种入口：对话上下文里的功能实现用子 agent 独立复核（避开实现者自证偏差）；审核 PR 用当前 agent 直接读 diff。
when_to_use	当用户认为一项功能实现完成、或要求审核某个 PR/分支是否达成原始需求时激活。触发示例：'这个功能做完了吗'、'对照需求看看实现全不全'、'帮我审一下这个 PR 有没有漏'、'验收一下这次改动'、'判断功能是否实现完成'。与相邻 skill 的边界：本 skill 只回答『相对原始需求，功能是否做完、缺什么』，不做代码风格/安全/性能的质量门禁（转 code-review-and-quality），不负责跑全量测试（转 run-all-tests），不负责判断是否破坏公共契约的同步清单（转 contract-guard）。

Feature Completion Audit

1. 目的与定位

本 skill 回答一个问题：相对最初提出的需求，这项功能是否真的实现完成；如果没有，缺口在哪。

它不是代码质量评审，也不是测试执行器。它做的是「需求 → 实现」的对账：把原始需求拆成可核验的条目，逐条用真实代码、测试和运行证据去印证，最后给出客观的完成度结论。

判定的最高原则是客观取证：

• 只认证据（file:line、测试结果、diff、契约文档），不认「我已经实现了」这类自述。
• 严格区分「声称完成」与「证据可验证完成」，二者不一致一律按未完成处理。
• 既查遗漏（需求要但没做），也查偏离（做了需求没要的、或改了不该改的行为）。
• 不确定就标记为「待确认」，不替开发者乐观假设。

2. 两种入口（必须先判定）

进入本 skill 第一步，先确定当前属于哪种场景，二者执行方式不同：

入口 A：对话上下文里的功能实现 → 用子 agent 独立复核

适用：用户在当前会话中（可能就是你自己）刚完成了一项功能实现，现在要判断是否做完。

此时必须用子 agent 做核验，不能由刚写完代码的主 agent 自评——实现者对自己的产出有天然的自证偏差，自评会系统性高估完成度。

做法：

1. 主 agent 先整理审计输入包（见第 3 节），尤其是原始需求原文与改动范围（涉及的文件 / 提交）。
2. 用 Agent 工具派发独立子 agent承担第 4 节的维度核验。给子 agent 的 prompt 里只给原始需求 + 改动范围 + 取证要求，不要把「我觉得已经实现了」「这块应该没问题」这类主观结论塞给它，避免污染判断。
3. 子 agent 各自读真实代码、跑/查测试，返回结构化裁决（每条需求：达成 / 未达成 / 部分 / 待确认 + 证据）。
4. 主 agent 汇总各子 agent 结论，做交叉核对与去重，产出第 5 节报告。

子 agent 拆分建议（按改动规模二选一）：

• 小改动：派 1 个核验子 agent，覆盖全部六维。
• 中大改动：按维度分组并行派多个（例如「需求覆盖 + 验收对齐」一组、「正确性边界 + 契约集成」一组、「测试证据 + 范围偏离」一组），主 agent 汇总。

入口 B：审核 PR / 分支 → 用当前 agent 直接做

适用：用户给出一个 PR、分支或一段 diff，要求审核是否达成需求。改动不是当前会话产出的，没有自证偏差问题。

此时直接用当前 agent完成全部核验，不必派子 agent。先取 diff 与关联需求，再按第 4 节逐维核验。

# 取 PR 改动范围（示例：相对 dev/main）
git diff --stat origin/main...HEAD
git diff origin/main...HEAD
# 或用 gh 拉 PR 元信息与原始需求描述
gh pr view <number> --json title,body,files

3. 审计输入（必读）

按存在与否尽量收齐，缺哪项要在报告里点明「证据不足」：

1. 原始需求原文——最高权威源。优先级：用户在会话中给出的需求描述 > .specs/<feature-name>/brief.md > .specs/<feature-name>/acceptance.feature > PR/issue 描述。
2. .specs/<feature-name>/acceptance.feature（若存在）——逐条 Given/When/Then 是核验清单的天然来源。
3. .specs/<feature-name>/technical_design.md、implementation_report.md（若存在）——了解设计意图，但不能当作「已完成」的证据。
4. 实际代码改动——git diff、关键文件、src/ 下相关模块。
5. 测试证据——tests/unit、tests/integration、tests/acceptance 下对应用例是否存在且通过。
6. 受影响的对外契约文档（若改动涉及）——docs/api/、docs/internals/ 下相关条目。

注意：brief.md / acceptance.feature / technical_design.md / implementation_report.md 是 .specs/<feature-name>/ 下的临时产物，可能不存在；不存在时以会话中的需求原文为准，并在报告里说明依据。

4. 六个核验维度（固定）

对每一项需求条目，从以下六个角度独立取证。每个维度的结论都要落到具体证据，不允许空泛判断。

1. 需求覆盖度（Coverage） 把原始需求拆成离散条目，逐条映射到实现位置（file:line）。明确列出：已实现、未实现、只做了一半的条目。这是完成度的主轴。

2. 验收对齐（Acceptance alignment） 若存在 acceptance.feature，逐条 Given/When/Then 核对是否有对应实现 + 对应测试。无验收文件时，依据需求原文自行归纳验收点再核对。

3. 正确性与边界（Correctness & edge cases） 不只看 happy path：异常路径、空/边界输入、并发与幂等、失败回滚是否被处理。需求隐含但未明说的边界也要点出。

4. 契约与集成一致性（Contract & integration） 本项目重点：改动是否影响 MQ topic/消息结构、HTTP 接口、MySQL schema、Qdrant/ES 索引、OSS 路径、错误码等公共契约；跨端（Java ↔ Py）取值是否仍一致。发现契约改动但文档/对端未跟进，记为缺口。

5. 测试证据（Test evidence） 新增/变更行为是否有测试覆盖，且测试实际通过。只有测试文件、没有运行结果，不算证据。关键路径缺测试记为 Required 缺口。

6. 范围偏离（Scope & deviation） 反向检查：是否实现了需求没要求的东西（过度实现）、是否顺手改了不相关行为、是否偏离了需求约束。偏离同样是「未按需求完成」的一种。

5. 输出报告

无论入口 A / B，最终报告结构一致：

1. 审计范围——原始需求来源、改动范围（文件/提交）、依据的输入文档、入口类型（A 子 agent / B 当前 agent）。
2. 需求条目对账表——逐条列：需求条目 | 状态(达成/部分/未达成/待确认) | 证据(file:line 或测试结果) | 缺口说明。
3. 六维核验小结——每个维度一段，点明发现的缺口与偏离。
4. 缺口清单（分级）：
   • Blocking：核心需求未实现 / 实现错误 / 关键契约破坏——功能不能算完成。
   • Required：需求偏差、关键路径缺测试、边界未处理——需补齐才算完成。
   • Suggestion：不影响「是否完成」判定的改进项。
5. 完成度结论——三选一，必须基于证据，不得乐观假设：
   • COMPLETE：所有需求条目证据可验证达成，无 Blocking/Required 缺口。
   • INCOMPLETE：存在 Blocking 或 Required 缺口（列出具体条目）。
   • INSUFFICIENT_EVIDENCE：关键证据缺失（如测试未跑、需求原文不全），无法客观判定，列出还需补什么。
6. 下一步建议——补实现 / 补测试 / 同步契约文档（转 contract-guard 或 doc-maintenance-sync）/ 跑全量回归（转 run-all-tests）。

6. 客观性自检（收尾前必过）

输出结论前，逐项确认：

• 每条「达成」都挂了可追溯证据（file:line 或测试结果），没有仅凭自述下的结论。
• 入口 A 的核验由子 agent 完成，主 agent 未把自评结论灌给子 agent。
• 同时查了遗漏和偏离两个方向。
• 不确定项标了「待确认」，没有为了给出 COMPLETE 而忽略疑点。
• 完成度结论与缺口清单自洽（有 Blocking/Required 就不可能是 COMPLETE）。