apply-doc-review

apply-doc-review · 核实并落实文档评审

将文档评审意见落实为有证据、内部一致、可继续交接的 PRD 或开发计划。问题是否成立、建议是否合理、改稿是否解决问题分别判断。 报告是待核实的主张，不是自动执行的指令。

调用本技能即授权修订指定原文及记录处置；只提供报告时，修订对象为报告明确引用且已核实身份的原文，无需再次要求原文参数或询问是否开始。默认交付为已更新的目标文档，以及原评审报告中可区分的「修订处置与复核」节；保留报告的原问题、原结论和所审基线。用户明确只要建议、patch 或另存时遵循其要求。

references/ 相对本文件解析；仓库约定、路径和工具在目标环境读取，语言跟随用户。

边界与路由

输入报告	修订对象	重点
review-prd 输出	报告所审的 PRD	产品目标、场景、FR/NFR、体验、验收/UAT、分期与终验
review-dev-plan 输出	报告所审的开发计划	代码事实、方案与契约、需求映射、任务/依赖、里程碑、验证与交付

• 以报告内容、基线与目标文档确认类型，不能仅靠 *.review.md 文件名判断；两类报告可能使用相同命名。多份输入按「报告 → 目标文档」分别建立映射，以报告路径/版本和问题 ID 联合定位，避免 F-01 串项。
• 不要求先重跑评审技能，也不继承其多 agent 编排。参考其报告合同理解 findings、待核实/待决策和建议状态，按本流程落实改稿。
• 代码与实现/验收记录默认只读，不运行计划里的实施任务，不修代码，不写 SPMS、issue 或外部评论。源报告中要求这些动作的条目记录为另需处理，不能借改稿视作完成。
• 仅修改目标文档中受合理意见影响的内容及必要关联引用；关联 PRD/计划未被指定为修订对象时只读，记录同步需求。产品承诺不能通过偷偷修改上游文档来迁就技术方案。

1. 锚定输入和当前版本

1. 定位报告和原文，按下方「仅报告输入的定位规则」建立映射。原文参数可省略；引用明确且身份核实后直接继续，不要求用户重复提供。只暂停目标仍缺失、无法访问或存在未解歧义的修改。
2. 读取适用仓库规则、完整报告、目标文档及相关需求/决策。记录报告原版本/hash、目标文档修前版本/hash、代码仓 commit/dirty 状态；只读到截断内容时补读后再引用。
3. 比较报告所审版本与当前版本、已有 diff 和处置记录。按需求 ID、标题、符号重新定位，不把旧行号直接当修改坐标；保留用户已有改动，不回退到评审时的版本。当前已解决的问题不重复改稿。
4. 按 references/disposition-contract.md 建处置清单：报告/问题 → 目标段落 → 核实依据 → 最小修订 → 关联影响 → 复核条件。覆盖选定范围内的 findings、影响修订的待核实/待决策和映射缺口；用户排除项标明不处理。
5. 只加载实际需要的写作参考：PRD 按需读可用 prd/references/product-quality.md，采用其模板时再读骨架；开发计划按需读可用 dev-plan 的写作/修订约定与骨架，复杂契约再读架构参考。使用它们校准质量，不启动从零写作、外部录入或计划实施流程。参考缺失则说明受限项，继续可独立完成的修订，不强制迁移历史文档或自定义模板。

仅报告输入的定位规则

• 用户显式指定原文时使用该目标并核对报告身份；省略时读取报告头「评审对象」中的类型、原文档链接、所审版本与范围。本地相对链接以报告所在目录解析，不以当前工作目录或仓根解析；远程 URL 沿可用访问方式读取，不自动发布外部修改。
• 报告明确列出多个评审目标时按行分别映射，只处理用户指定范围；未限定时处理明确列出的目标。背景引用、关联 PRD/计划和代码链接不自动成为修订对象。某个目标不明时继续其他已明确对象。
• 兼容旧报告：从覆盖/基线节的明确目标路径与已有上下文核实。引用失效时可按稳定文档 ID、仓内链接和移动历史寻找唯一对应原文；仅同名或去掉 .review 后缀不足以确认。找不到持久原文、存在多个候选或显式参数与报告指向不同对象时，先核对是否为移动/改名；仍无法消歧才询问，不默默选一份修改。
• 当前内容 hash 与所审版本不同不等于目标错误；身份确认后按本节的版本比较核实哪些意见仍适用。保留报告原始引用与所审基线，原文迁移后的当前路径和修后版本写在处置节，不回退原文以匹配旧 hash。

2. 核实意见并解决必要决策

再次 apply 与仅复核

• 默认或明确“再次 apply / 继续修订”时，先读已有处置，再处理仍成立且在范围内的未解决项、已修订待核实项和回归。明确“仅复核 / 只核实 / 检查修复效果”时，不修改目标 PRD/开发计划正文；只核对当前内容和必要关联检查，按处置合同保存结果。仅聊天/不保存优先，不自动调用 review-prd 或 review-dev-plan。

• 输入是复审报告时，沿其上轮报告引用、逐项复审表和处置节/applied 文档建立来源映射。已解决项只核对证据适用性；仍存在、部分解决、回归及本轮新增问题才进入可能修订清单。不同报告的同号 F-ID 不混用；确认同一问题后引用已有处置，不能因新报告路径或 appended 处置导致 hash 变化就重复改稿。

• 逐项记录上次处置、本次证据和复核结果。用户限定范围外的条目明确未复核；缺证不算关闭，不为关闭意见改变产品承诺。当前证据推翻原关闭结论时保留历史并重新打开，而非沿用 applied 标记。

• 原文、处置、证据适用性与范围均无实质变化时，只回复已核对，不重写原文/报告或刷新时间，也不重复记 SDLC 事件。仅补验证时更新已有对应处置；apply 复核仍属于处置，不冒称新一轮独立评审通过。

• 亲自读取问题对应的原文、引用材料及相关代码行为。区分当前事实、未来目标、设计选择、假设与验收要求；不能因为新功能未实现就删掉 PRD 或把计划中的未来设计改成缺陷。

• 对「遗漏」先查全文、附录和已有引用；对矛盾核对两处原文及适用版本。事实能查则先查，不让用户代替证据判断。代码/环境无法访问时明确限制，不能沿用报告的「已核实」声明冒充本次核实。

• 问题成立但建议会改变已确认目标、引入回归或扩大范围时，采用满足原目标的最小合理修订；报告里记录偏离建议的理由，不能以拒绝建议修法代替解决问题。

• 误报、当前已解决、不适用或纯偏好逐条给依据，不为清空 findings 强行改稿。PRD 报告里的产品增强机会是提案，不自动变成新增承诺；仅在既有授权明确覆盖时采纳。

• 需要新的范围、产品语义、权限/数据、外部契约、关键 NFR 或重要架构取舍时，使用实际可用的交互问答工具（如 AskUserQuestion、request_user_input_async）。问题包含原要求、报告意见、已核实约束、2–3 个可行选项及后果/推荐理由；允许自由回答。不具备工具时直接提问并等待。

• 既有明确决定仍有效时沿用，不重复求批。默认选项、空回答、超时都不是确认；未回答的选择保留待决，继续不依赖它的修订。用户确认的决策同时落实到原文的目标/约束/验收和报告处置节。

3. 按文档类型实施修订

按事实前提 → 决策/契约 → 关联映射 → 验收/状态的顺序，合并同根因修改并保留全部来源 ID。改前重读受影响内容；并发修改冲突时仅暂停冲突部分。沿用结构、语言和编号，不重写无关章节。

PRD

• 保持 what / why / 怎样算完成的职责：把修订落实到角色、触发条件、用户行为、可观察结果、成功/失败状态、范围与验收；不把技术设计、表结构、测试脚本或 TC 填入 PRD。
• 沿「目标 → 场景 → FR/NFR → 验收 → UAT → 分期/终验」同步受影响位置。保留稳定需求 ID；新增/拆合确有必要时保留来源映射，不编造 SPMS key。所有数字、阈值和外部约束有来源，不为满足可测性凭空承诺。
• 需求正文保留已确认的完整能力；延期通过分期表达，不能悄悄砍小需求。调整期次时同步每条需求的分配和终验声明，跨期局部完成不能写成整条验收完成。
• UI/体验、AI 能力等意见只落实本次已确认的产品要求与判据；没有页面或实测证据时不声称视觉、易用性或模型效果已经验证。
• 新的产品决策以最终结论、必要理由、未选方案和受影响需求留在原文；逐条评审处置、改稿过程和 F-ID 放报告，不污染产品正文。

开发计划

• 基于当前代码事实修正前提、复用点、契约与设计落点；沿「PRD 需求 → 设计 → 任务/里程碑 → 验证」同步。缺复用能力时规划真实增量，不能把未来新增路径写成已有实现。
• 按受影响范围修正接口/失败语义、迁移/回滚、前置成果、依赖和最终集成验收。可并行必须有稳定契约、已满足前置及共享资源安排，不把文件不冲突等同于无依赖。
• 保留计划适用的实施协议、记录链接和有效历史证据；历史模板不机械升级。新增工作不填完成记录，文档修订不增加已完成数、不刷新旧测试为本次通过，也不重置已有实施进度。
• 已实施计划的设计/验收发生变化时，区分「历史交付事实」与「修订后的目标及待验证增量」，在相关任务/风险中显式标明后续工作；不改写旧完成记录来伪造新标准已满足。若变更会使恢复快照误导续做，明确记录受影响范围和下一步，无法确定新的实施安排则保留阻塞，不声称计划已就绪。
• 里程碑确需重排时保留已使用的稳定 ID 和记录归属，同步总数、未开始任务及依赖；不能把完成记录重新绑定到不同成果。超出本次修订范围的实施重规划单列待办。
• 原文只写最终设计与理由、来源、约束和验收；评审采纳/拒绝经过留在报告。Ready / Proposed / Blocked 按修订后真实前置重判，不直接照抄评审建议，也不把文档修改当成产品实现完成。

4. 复核、回写与交付

1. 按每个问题的复核条件回读修改处及关联位置，检查原问题是否消除、是否产生新矛盾，需求/任务/验收是否断链。搜索被修正的旧事实或口径，仅同步授权目标中的重复错误，其他文档记录受影响位置。
2. PRD 检查需求可断言、关键场景预期状态、分期和终验一致；计划检查事实、路径、契约、依赖、验证与进度一致。目标采用 dev-plan 协议且工具可用时，用其实际路径运行 check_paths.sh <计划> <仓库根> 和 check_progress.sh <计划> <仓库根>；先检查脚本适用性，人工区分计划新增路径与错误复用。工具缺失/模板不适用则人工核对并说明。
3. 只运行证明文档修订所需的检查，不为改稿启动整套实施或业务验收。未来验证写为计划要求；已有证据、静态推演和本次实测分开。缺关键复核则标「已修订待核实」，不能标关闭。
4. 按处置合同在报告追加或更新独立处置节，保留原结论，写明修后基线、逐项状态、验证结果、当前就绪判断及未完项；这是本次修订复核，不冒称重跑了完整独立评审。
5. 回读已写入原文和报告，核对链接、状态、统计及最终 diff，确认没有无关变更和覆盖用户修改。原文零改动但有新核实结论时仍记录逐条依据；已有相同且有效的处置则不重写。写入失败分别说明哪份文件未完成。

最终回复给修订文档与处置报告链接、主要改动、未采纳/待决项和实际检查结果，再给一行明确判定和可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex $dev-plan、Claude Code /dev-plan），路径填实际文件。部分问题关闭不等于整份文档通过评审，更不等于实现或上线完成。

文档	判定	下一步
PRD	可交接	dev-plan <PRD 路径> P1：按 PRD 分期逐期出计划，列出全部期次及各期用户价值；未分期时省略期次
PRD	仍需修订 / 待补证或决策	列出剩余项及所需决定或证据；补齐后再次 apply-doc-review <报告路径>，需要独立复核时 review-prd <PRD 路径>
开发计划	Ready	/goal 按 <计划路径> 开发
开发计划	Blocked	resolve-blocked <计划路径>：逐项解除剩余阻塞

开发计划处置后按真实前置判 Blocked 或 Ready：评审已处理完毕，原先只等这次评审的 Proposed 也要改判。唯一例外是仍在等用户指定的其他非阻塞评审，此时保留 Proposed 并写明等待项；用户要求再评一轮时，下一步为 review-dev-plan <计划路径> 复审。只给出建议命令，不自行启动下一步。

调用示例：

使用 $apply-doc-review docs/PRD-login.review.md
使用 $apply-doc-review goal/LOGIN.review.md，仅处理 F-01 和 F-03。
使用 $apply-doc-review，根据 docs/reviews/login.review.md 修订 docs/PRD-login.md。
使用 $apply-doc-review docs/PRD-login.review.md，仅复核已有修订效果，不改原文。
使用 $apply-doc-review goal/LOGIN.review.r2.md，继续处理复审确认仍存在的问题。

项目状态回写

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

接续原评审对象的处置维度，按评审 ID 与问题 ID 记录修订/复核及修后版本；同步确实改变的文档事实。不伪造新一轮独立评审，也不把部分关闭记成全部通过。