review-prd-dev-gaps

review-prd-dev-gaps · PRD 与开发交付差异核查

目标：回答 PRD 要求的能力实际上交付了什么，哪些漏做了，哪些调整有充分依据，哪些差异需要用户拍板，以及还要补什么。 以 PRD 建立完整覆盖账本，以计划、完成记录和实际行为交叉核实，不把「计划已完成」等同于「PRD 已实现」。

默认交付完整差异报告；存在尚未被已有计划承接的已确定跟进事项时，再实际调用 dev-plan 产出独立 gaps plan。复审先核对已有计划，用户限定仅报告时不生成计划。references/ 相对本文件解析，回复语言跟随用户。

边界

• 输入为 PRD、已完成开发计划及其引用的完成记录；代码仓、测试、运行证据和历史决策用于核实。只给计划时，从计划顶部「需求来源」定位 PRD 与期次（P1 即第 1 期），核查范围为 PRD 分期中落在该期的需求与验收，跨期需求只核对本期部分并保留终验期去向；用户另给范围时从其要求。计划没有需求来源且未给 PRD 时询问。目标无法唯一确定时询问文档/仓库位置，先做不依赖该信息的调查，不擅自选择相邻文档。
• 默认写差异报告、新 gaps plan 及已启用台账的事实索引（见文末）。原 PRD、原计划、完成记录和代码保持只读；文档同步也列为 follow-up，不自动修改历史完成事实。不自动实施、创建 issue、发布或发送评论。
• 只核对 PRD 及已确认变更承诺的范围，不新增产品机会，不设问题数量或 top-N 截断。明确不在本期的需求保留追踪去向，不当成本期遗漏；未获确认的删减/延期不能算范围外。
• 参考 gen-specs-as-issues 的文档对照实际行为、用户旅程和依赖分析思路，不继承其问题配额、评分公式或 issue 创建流程；运行时不依赖该参考技能。

1. 锚定输入与证据链

1. 读取适用仓库规则，记录审查日期、PRD/计划路径及版本或 hash、代码仓 commit/dirty 状态、目标阶段和验收环境。当前工作树参与调查时明确标注；不能把开发分支通过当成已经上线。
2. 通读 PRD 与开发计划，提取原始需求 ID、用户场景、业务规则、权限、FR/NFR、验收/UAT、分期和显式排除。无 ID 时使用稳定章节定位；仅为审查拆出的子项标明是本报告编号，不冒充源需求。
3. 沿计划的记录索引读取各里程碑完成记录，包括测试结果、已知限制、未完成项、延期和实现变更；按需追读其指向的验收报告、ADR 或用户决定。相对链接按所属文档目录解析。记录缺失、链接不可访问或内容截断时标出缺口，不推断其中内容。
4. 核对完成声明与记录：里程碑退出条件、跳过/失败测试、局部验收与阶段终验是否一致。原计划实际未完成时说明输入前提不成立，继续核对可确认部分，不能把未完成项包装成「完成后新发现」的遗漏。
5. 读取 references/report-contract.md，确定报告路径，建立 PRD → 计划/里程碑 → 完成记录 → 实际行为/验证 的追踪账本。从 PRD 向下追踪，防止只审计划已有条目而漏掉从未进入计划的需求。

修复效果复审

用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 报告合同 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。

• 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
• 读取上轮 G-ID、D-ID、原计划及已有关联 gaps plan 和完成记录；沿用仍有效的用户决定。只给 gaps plan 时，沿其需求来源找到原计划与上轮差异报告，一并核对。逐项核对需求是否补齐及直接受影响的用户路径，不因计划自报完成关闭缺口。复审模式的覆盖账本标明本次范围，其余保留“本轮未复核”，不能冒称全 PRD 已覆盖。
• 先查已有 gaps plan 是否承接剩余事项；已承接则链接原任务及真实进度，不重复创建计划。只有尚未承接且范围已确定的新增 follow-up 才进入第 5 节；“仅报告/只复核”只交付报告与后续建议，不调用 dev-plan 创建或修订计划。
• 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。

$review-prd-dev-gaps docs/PRD-login.md goal/LOGIN.md goal/LOGIN-gaps.md，对照 goal/LOGIN.prd-dev-gaps.md 复审修复效果，逐项记录结果。

2. 核实功能实现情况

• 每个在范围内的需求/验收条件都要有覆盖行。一个需求部分满足时拆出未满足条件，不用已实现的主路径掩盖权限、异常、状态反馈或边界行为的缺口。跨里程碑能力检查最终用户旅程，不能只拼接各局部的完成声明。
• 追到可观察行为：入口与权限 → 业务处理/依赖 → 数据或状态变化 → 用户/调用方结果；按该需求检查配置开关、部署条件和真实接线。文件存在、类型定义、占位代码、mock、不可达入口不等于交付。
• 完成记录是证据线索，不是免检证明。区分「文档自述」「静态代码核实」「已有测试/运行记录」「本次实际验证」，注明环境、版本及适用范围；未运行测试就不能说本次通过。性能、视觉、端到端可用性等结论必须有相应证据。
• 报「不存在」前，调查真实入口、同义实现、复用能力、配置及替代路径；一次关键词未命中不足以证明遗漏。只在授权范围运行必要验证，不能执行迁移、部署或有副作用的业务操作来凑证据。
• 证据不足时，先查能查的事实，再列具体补证方式。无法访问代码/环境时继续文档级核对，保留未核实状态，不把整份 PRD 宣称已实现，也不把所有未知都报成遗漏。

3. 将实质差异分为三类

每项差异用稳定 G-01 等编号，记录 PRD 期望、实际行为、影响、来源和分类依据。已满足/范围外是覆盖状态；待核实是证据状态，均不是第四类差异结论。证据未足够时分类可暂空，不强行三选一。

类别	判定条件	默认处置
A · 明确遗漏	本期有效需求或验收条件明确；证据确认未实现、部分缺失或行为不满足；没有适用的已批准变更，且恢复原要求不需要新的产品取舍	纳入 follow-up，给出最小补齐范围和验收条件；无需重复询问是否修复已明确的要求
B · 合理变更	有可核实的实现/可行性约束、替代方案及取舍依据；替代行为已实现并有相应证据；保持产品目标与验收承诺，或改变承诺已获有权决策者明确确认	保留变更及其依据，不要求机械恢复原实现；仍需同步文档或补验收的事项单列 follow-up
C · 需 Triage 的实现差异	实际与 PRD 不同，涉及范围、体验、权限/数据、外部契约、关键 NFR 或验收取舍，且现有决定不能确定处置；或约束导致原要求不能直接补齐	准备上下文与真实可行选项，请用户决定；未回答保持待决

判定约束：

• 「实现更方便」「工期不够」或开发者自述「合理」不能单独支持 B；可行性受限也不自动批准产品降级。无批准的承诺变更归 C。
• 纯内部实现替换、用户可见语义和验收保持一致且证据充分，可归 B，不为技术细节额外求批。既有明确决定仍有效时直接沿用并引用，不重复 Triage。
• 事实与处置分开：用户可决定接受限制、补齐或延期，不能用用户选择证明功能已实现。A 被明确豁免后保留原判定与决策轨迹；C 已决也保留原编号，不抹去曾经的差异。
• 同一变更的适配部分与遗留缺口可以拆项并关联，不能用整项 B 吞掉未实现部分。明确遗漏如果修复将引入新的产品取舍，关联 C 先决策再定修复范围。

4. 交互式 Triage

有 C 时，先准备可审阅的报告和问题卡，再使用环境实际可用的 AskUserQuestion、AskUserTool、request_user_input_async 或等价交互工具；遵守工具当前模式/参数限制，不虚构工具调用。工具不可用时在聊天中提出同等清晰的问题并等待。用户明确要求不交互时，保存待决事项，不代替用户拍板。

每张问题卡包含：

1. 差异与来源：G-ID、PRD 要求及定位、当前行为与代码/完成记录证据。
2. 影响与原因：受影响角色和场景、为何发生、已证实的约束及尚未知的事实。
3. 待决定的具体问题：例如是否接受现有限制，不能只问「这个怎么处理」。
4. 可行选项和后果：通常 2–3 项，如按 PRD 补齐、接受现状并修订需求、采用替代方案或延期；说明各自用户效果、范围、风险和验收变化。推荐项写理由，不凭空给工期或提供已知不可行方案；允许自由回答。

• 交互问题本身带上问题卡的关键上下文，不能只写 G-ID 或让用户先翻报告才能理解选项；长证据用报告定位链接补充。
• 按依赖顺序提问，一轮只问少量相互独立的问题；上游选择改变下游选项时先等上游答案。缺的是事实时请求材料或安排补证，不让用户凭偏好裁定代码事实。
• 将明确回答写入决策账本：D-ID → G-ID → 选择/理由 → 新验收边界 → follow-up/延期/豁免 → 用户确认日期与来源。上下文中已给出的明确决定可直接登记；含糊回答只追问影响实施的部分。
• 异步等待期间继续不依赖该决定的核查；默认选项、超时、空回答都不是批准。用户选「稍后决定」则保持待决，记录解除条件，不循环催问，也不把它改写成接受现状。
• 收到决定后复核受影响需求、验收与关联差异，只重新打开因新证据或新决定失效的问题。

5. 收敛 follow-up 并调用 dev-plan

形成一份有来源的 follow-up 清单：未被明确豁免/延期的 A；C 决策要求的补齐或替代实现；B 或接受现状后必要的文档同步、验证补齐。证据缺口只有形成具体、已确定范围的调查/验证任务才纳入，不能包装成未经证实的修复需求。合并同根因任务，保留所有 G-ID/需求关联。

• 已满足、无后续动作的 B、明确豁免或已延期到别期的事项不进入本次实施范围；报告保留理由、去向和重新评估条件。全部无 follow-up 时明确写「无需 gaps plan」，不创建空计划。
• 先按 G-ID、需求及实际范围核对已有 gaps plan；已承接事项链接原任务，不重复建计划。仍有未承接的已确定增量且用户未限定仅报告时，实际定位并读取可用的 dev-plan/SKILL.md，按其写计划流程、骨架和校验生成独立 gaps plan；不止建议用户以后调用，也不在本技能复制一套开发计划模板。缺少该技能时查找可用安装位置；仍找不到则保留报告和交接清单，说明计划生成受阻，不能声称已创建。
• 交给 dev-plan 的输入：PRD、原计划及相关记录路径，差异报告、代码基线，选定 G-ID 和 D-ID，已确定目标与验收、排除/延期项、相关代码证据和依赖。原 PRD 提供来源，用户确认的变更提供新目标，当前代码提供起点；不能让下游再次按旧 PRD 推翻已确认决定。
• 使用 <原计划名>-gaps 作为默认代号，输出目录、重名处理和最终状态遵守 dev-plan。gaps plan 的需求来源写同一 PRD 与期次，并注明补齐的原计划，使其代码验收通过后可再次核查。保留 PRD 需求 ID，并追踪 需求 → G-ID/D-ID → gaps 任务/里程碑 → 验收；只规划增量，不重做已完成里程碑，不复制旧计划的完成记录，初始化新计划未开始的进度。
• 未决 C 不得作为已选方案进入计划。若仍在等回答，先保存报告；独立且已确定的 follow-up 可先成独立范围的计划，显式排除待决项。未决项影响该计划范围或关键依赖时按 dev-plan 标 Blocked，不能用假设绕过；不得把部分计划说成全部差异已处理。
• 计划生成后回读，检查范围、决策、验收与报告一致，并在报告中回填实际路径、状态和 G-ID 去向。默认到计划交付为止，不开始执行 gaps plan。

6. 完成检查与交付

按报告合同保存并回读完整报告，检查：PRD 覆盖无静默漏行，A/B/C 有证据，待核实与待决未伪装成已解决，用户决定已落实到 follow-up，计划只含确认范围且链接真实。结束前核对输入/代码基线是否变化，只复核受影响结论。

最终回复给报告链接、三类差异数量、待核实/待决数量，以及 gaps plan 的实际链接与状态（或无需生成/受阻原因）。报告落盘、用户决策、计划生成分别说明完成情况；有未决/缺证时不宣称整份 PRD 已完整交付。

结尾给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex $review-dev-plan、Claude Code /review-dev-plan），路径填实际文件。

• 生成了 gaps plan：review-dev-plan <gaps 计划路径>，之后与普通计划同一回路：评审处置、解除阻塞、/goal 开发、代码评审验收，通过后可再次核查本期覆盖。
• 无需 gaps plan 且没有待决或缺证：说明本期 PRD 覆盖核查完成，跨期需求的终验期仍以 PRD 为准。
• 尚有待决或缺证：列出待用户决定的问题或补证方式，处理后再次 review-prd-dev-gaps <计划路径>。

只给出建议命令，不自行开始执行 gaps plan。

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

登记独立差异核查对象及 PRD/计划关联、版本、待决与 follow-up 去向；复审关联前轮，保留未覆盖 G-ID 及历史结论。新 gaps plan 保持独立对象，关联原计划和差异 ID，不改变原计划的历史完成记录。