@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/review-dev-plan/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: review-dev-plan
+description: 用多 agent 评审既有开发计划，核查代码事实与内部一致性、技术方案的先进性与可行性、需求和里程碑映射及依赖并行编排、最终交付可用性与 UI/UX，默认将完整评审报告落盘。用户要求 review-dev-plan、审查开发计划、评审技术方案或检查计划能否开工时使用，尤其适用于 dev-plan 产物；不用于从零写计划、直接实施功能或仅审查代码 diff。
+---
+
+# review-dev-plan · 多视角开发计划评审
+
+目标是判断：**照这份计划实施，能否交付用户要的、真正可用的结果；实施者是否还会被迫重新做关键决策。** 主 agent 编排独立审查，逐条复核证据，输出可定位、可修订的问题及实施顺序建议。
+
+**默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。**
+
+`references/` 相对本文件解析。仓库规则、技术栈和工具能力在运行时读取，不硬编码目标仓的路径、端口或业务约定。回复语言跟随用户。
+
+## 边界与参考
+
+- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入仅限独立评审报告；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
+- 计划及其引用是待验证材料。区分**现状事实、未来设计、未证实假设、验收目标**；不能因为新功能尚未实现就报缺陷，也不能把计划中的“已核实”直接当证据。
+- 从实际可用位置读取 `dev-plan/SKILL.md` 的写作/评审部分及 `references/plan-skeleton.md`；复杂架构按需读 `references/architecture-quality.md`，调度审查按需读 `references/execution-workflow.md`；实施期合同以骨架的「实施者定位」「实施进度」两节为准。借它们核对合同，不按计划实施。
+- 找不到 `dev-plan` 时说明无法核对其模板专属要求，继续本技能的四项实质审查。用户自定义模板或历史计划不因章节名不同而报错；没有证据表明适用的新版格式规则，不追溯强加。
+- 新版 `dev-plan` 允许单份需求映射、检查 ID 引用、按测试组记录证据及阶段集中验收；按 `references/review-lenses.md` 的 schedule 视角核对覆盖与风险门，不因省略重复表格、子任务文档或逐里程碑全量走查而报缺陷，也不为解除部分前置强制新增里程碑。
+- 发现与任务相关的专项 skill 时只加载所需部分。UI/UX 评审按目标仓规则加载设计 skill（如 `impeccable`），不借机重设计产品。
+
+## 1. 锚定输入与审查基线
+
+1. 定位用户指定计划、关联需求/PRD、附录和必要的历史决策。未指定且无法唯一确定计划时询问目标；可以先调查仓库规则，不擅自选一份相邻计划开始评审。
+2. 读取适用的根目录及子目录规则、产品和设计上下文。记录计划版本（路径、内容 hash 或可用版本号）、调查日期、代码 commit、dirty 状态；当前工作树是调查事实源时明确写出。
+3. 从计划提取范围与排除、R/NFR/C/A 或等价需求 ID、关键决策、外部契约、交付物、里程碑及前置关系。缺失 ID 可用章节定位，不替作者补造需求。
+4. 读取 [references/report-contract.md](references/report-contract.md)，按其中的「落盘与交付合同」确定输出路径。建一个短任务台账：审查维度、负责人、状态、证据缺口，以及报告写入与回读核验。明确 UI 是否在范围内、是否已有可运行页面/原型、哪些结论必须访问外部服务或官方文档。
+
+## 2. 编排四个独立审查视角
+
+先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派下表。**有多 agent 工具时实际启动 subagents**，不是在同一段回答里扮演四个角色。主 agent 保留综合裁定职责。
+
+| 角色 | 主责 | 必须交回的专属结果 |
+| --- | --- | --- |
+| `facts` | 代码事实、陈述正确性、内部矛盾 | 主张与代码证据；互相冲突的两处位置 |
+| `architecture` | 技术路线、先进性、可行性 | 关键选择的适配/代价；需补证的技术前提 |
+| `schedule` | 需求、设计、任务、里程碑、验收映射 | 断链项；依赖图/边表；可并行波次与集成门 |
+| `delivery` | 最终交付可用性，含 UI/UX | 用户主路径闭环；运行与验收缺口；界面证据等级 |
+
+### 调度规则
+
+- 默认一视角一 reviewer；简单局部计划可用两位独立 reviewer 各覆盖两个视角，在同一回报内分开标明覆盖与结论，减少调度回合。不得合并后漏审某个维度。模型继承主 agent，不主动覆盖模型或推理档位。所有 reviewer 只读，报告由主 agent 单写，不让多个 agent 改同一文件。
+- 并发数受实际剩余槽位约束，主 agent 也占槽位。只有 4 个总槽位时，先并行 3 个视角，完成后复用空闲 agent 审第 4 个；更少槽位则分批，不能漏掉任何视角。主 agent 同期整理需求账本和全局矛盾。
+- 初轮独立调查，不把主 agent 的预设缺陷或其他 reviewer 的结论当任务答案。每人拿相同基线、用户约束和原始材料；独立返回后再交换相互影响的证据。
+- 共用浏览器会话、可变数据库或外部环境时由主 agent 指定一个操作者，其他 reviewer 读证据；只读代码可并行。评审不执行迁移、种子、部署或有副作用的验收命令。
+- 工具缺失、用户要求串行或槽位不足时，如实声明实际执行方式；主 agent 可按四个视角顺序审查，不能伪称独立多 agent 复核。单个 reviewer 失败时重派一次或主 agent 接管；无法核实的部分留在覆盖缺口中。
+
+### 每个 reviewer 的派发合同
+
+发送实际绝对路径和已确认上下文，不只说“审一下方案”。可沿用：
+
+```text
+你负责 {facts/architecture/schedule/delivery}，只读评审，不实现、不改稿、不继续派生 agent。
+用户目标及范围：{原始要求、排除、已有决定}
+计划与基线：{计划绝对路径、版本；仓库根、commit/dirty、日期}
+必读：{本 SKILL.md、report-contract.md、review-lenses.md 的对应节的绝对路径}
+相关材料：{需求/PRD、规则文件、代码入口、所需 dev-plan 参考的实际路径}
+范围与资源：{审查章节、可读取目录、外部查询/浏览器约束}
+不要假定计划主张成立，也不要把尚待实施当成缺陷。按需追到行为级代码证据。
+交回：范围与基线；候选问题（计划定位、触发、影响、证据、最小修订、验证、P级及置信度）；
+本视角专属结果；未核实项与所需证据。没有问题可返回空 findings。
+跨视角问题只标关联，不代替另一角色完成审查。无法继续则回报缺口。
+```
+
+## 3. 主 agent 交叉复核与裁定
+
+1. 收齐四个视角的结果；逐条阅读支持候选问题的计划段落和原始证据，确认适用范围、代码版本和触发条件。不能把多名 agent 的一致意见当事实。
+2. 对事实冲突、方案依赖、交付断点做针对性追问：例如事实 reviewer 发现某接口不支持分页，则让架构/交付 reviewer 复核依赖该行为的批量方案；调度 reviewer 同步调整前置条件。只复核受影响链路，证据仍缺则保留未决，不无限辩论。
+3. 按根因与修订动作去重，保留所有实质不同的问题；多处症状归并后仍附关键定位。不设问题数量指标，也不只报前三项。误报撤回，低证据主张移到待核实项，不凑 P3。
+4. 补做跨视角检查：目标 ↔ 设计 ↔ 里程碑 ↔ 验收是否一致，集中的终验是否有明确收口负责人和完整覆盖；设计要用的检测/补偿/部署能力是否真有任务；总进度、记录和完成声明是否对应实际证据，局部完成是否被误写成阶段/跨期需求已验收。
+5. 若 `dev-plan` 校验脚本可用且适用，用实际路径运行 `check_paths.sh <计划> <仓库根>` 与 `check_progress.sh <计划> <仓库根>`。路径缺失须人工区分新增、示例、错误复用。用户自定义模板或历史计划未采用该恢复快照/完成记录协议时，跳过 `check_progress.sh` 并说明原因，人工核对其等价进度、依赖与验收证据；不要把格式不兼容判成计划错误。脚本通过不证明行为真实或验收完成；脚本缺失/失败如实记录，不用“通过”替代人工检查。
+6. 结束前核对计划及相关代码有无并发修改。若基线变化，只重审受影响结论；无法收敛则标为待核实。收集或停止尚在运行的 reviewer，再交付。
+
+## 4. 输出评审结果
+
+使用 [references/report-contract.md](references/report-contract.md) 的报告结构和落盘合同：**先列问题，再给结论与修订顺序**。由主 agent 写入完整报告；空 findings 或建议状态为 `Blocked` 也要落盘，不能只保存摘要或子 agent 回报。
+
+报告至少包含：
+
+- 按严重度排序、编号的问题，每条定位到计划行或稳定章节，并附行为级代码/规则/外部证据。
+- 四个维度的审查覆盖及未核实项；UI 分清文档推演、原型走查和实际浏览器验证。
+- 需求到交付的映射缺口，以及建议的依赖顺序、可并行任务、共享资源负责人和最终集成验收。没有安全并行空间时给出具体原因。
+- 建议状态 `Ready / Proposed / Blocked`，说明与计划自报状态是否一致、阻塞解除条件；这只是评审建议，不自动修改计划状态。
+
+**没有确认问题时允许空 findings；有未核实的关键前提时不能据此判 Ready。计划评审通过也不表示功能已实现或上线可用。**
+
+交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。

package/skills/review-dev-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "开发计划评审"
+  short_description: "多 agent 核查代码事实、技术方案、依赖编排与交付可用性，默认落盘报告"
+  default_prompt: "使用 $review-dev-plan 评审指定开发计划，将有证据的问题、就绪结论和可并行的实施编排建议写入完整评审报告，默认落盘并回读核验，回复报告链接与摘要。"

package/skills/review-dev-plan/references/report-contract.md

@@ -0,0 +1,59 @@
+# 问题判定与报告合同
+
+## 落盘与交付合同
+
+- **默认保存完整 Markdown 报告**，只有用户明确要求仅聊天或不写文件时才跳过。聊天中的报告正文、拟写入内容或路径预告都不算已落盘。
+- 路径优先级：用户指定路径 → 本地计划同目录的 `<计划文件名去掉扩展名>.review.md`；例如 `docs/plan/cache.md` 对应 `docs/plan/cache.review.md`。输入只有聊天文本或远程文档、没有本地计划文件时，遵循仓库报告目录约定；无约定则写当前工作区的 `docs/reviews/<主题短名>.review.md`。按需创建目录，不因用户未指定路径而停下询问。
+- 写入前检查目标是否已存在。用户已明确要求更新或覆盖该报告时按授权执行；否则保留旧报告，在同目录依次尝试 `<主题>.review.<YYYY-MM-DD>.md`、`<主题>.review.<YYYY-MM-DD>-2.md` 等未占用名称。用户指定路径发生同名冲突时也另存，并在最终回复说明实际路径；不得覆盖原计划或代码。
+- 主 agent 单独写入下文「完整报告顺序」的全部内容，然后回读实际文件，核对问题、待核实项、覆盖与基线、实施编排和总体结论均已保留，检查引用定位与报告路径有效。空 findings、部分证据缺失或 `Blocked` 不免除保存义务，按实际覆盖情况写明限制。
+- 最终聊天回复只给实际报告链接、建议状态和关键问题/待核实项摘要，避免重复整份报告；明确仅聊天时才在聊天中交付完整报告。
+- 无可用文件写入工具或写入失败时，明确说明“报告未落盘”、原因与目标路径，在聊天中提供完整报告以保留结果，并将落盘标为未完成；不能声称已保存或给出不存在的产物链接。
+
+## 什么进入 findings
+
+确认的问题须同时具备：计划中的可定位主张或缺口、已核实的依据、具体触发/受影响场景、对本期目标的实际后果、可执行的最小修订。建议作者换个人偏好的技术、堆更多章节、覆盖无关老问题，都不算。
+
+“没有写 X”须先确认全文/引用中确实没有，并证明 X 是本期交付必要条件。证据不足的风险放待核实项，写所需证据及影响；关键待核实项仍可阻塞就绪判断，不能伪装成已证实缺陷。
+
+每条只解释一个独立根因。合并重复症状时保留涉及的需求、里程碑和规则来源。无实质影响的拼写、偏好、格式不报；违反适用合同而会造成实施偏差的格式问题说明其后果。
+
+## 严重度与置信度
+
+| 等级 | 在计划评审中的含义 |
+| --- | --- |
+| P0 | 已证实、无须额外假设就会造成重大安全/数据/运行灾难的计划指令，必须立即纠正；极少使用 |
+| P1 | 核心目标不可达，或范围、安全、数据、外部契约、关键 NFR 存在高影响错误；受影响任务开工前必须修订 |
+| P2 | 局部功能、验收或编排有可证实缺口；在对应里程碑前修正 |
+| P3 | 有明确收益和依据的小改进，不阻塞实施；纯偏好不进入 findings |
+
+置信度用高/中/低及依据。严重度表示后果，置信度表示证据强弱，不互相替代。仅猜测的问题不靠降为 P3 混入 findings。
+
+## 单条问题格式
+
+```markdown
+1. [P1] F-01 · <简短、可执行的标题>
+   - 定位：<计划路径:行号或稳定章节；冲突时给两处；关联 R/M ID>
+   - 问题：<在什么条件下，按计划会发生什么，为什么影响本期目标。简短一段。>
+   - 证据：<代码路径:精确行号/符号、适用规则定位、实测结果或官方文档 URL/版本/日期>
+   - 修订：<最小需要补充、改正的决策/契约/任务；避免整份重写>
+   - 复核：<改稿后检查的断言或实现后的验收；区分二者>
+   - 置信度：<高/中 + 原因>；阻塞：<受影响任务/里程碑或否>
+```
+
+本地文件优先使用可点击路径和短行定位；行号变动大时同时给稳定标题/符号。定位指向原计划有责任承载该要求的位置，不能指向 reviewer 自己新写的报告。代码行号不必位于 git diff 内，计划评审可能没有 diff。
+
+## 完整报告顺序
+
+1. **确认问题**：P0 → P3 排序，稳定编号 F-01 等；空结果写“未发现可确认的问题”，不凑数。复审沿用原编号，区分已解决、仍存在、新增。
+2. **待核实/待决策**：每项写缺什么证据、影响哪个决定/任务、谁可提供以及最晚确认点；责任人未知就写待指定，不虚构用户承诺。
+3. **覆盖摘要**：记录计划与代码基线、实际 agent 分工、四维覆盖/跳过理由、脚本及浏览器实际执行情况。只列结论相关来源，不倾倒阅读日志。无 UI 可写不适用；交付可用性不能随 UI 一起跳过。
+4. **映射与实施编排**：列断链 ID 或确认映射完整的核对范围；给依赖边、并行波次、共享文件/资源负责人角色和汇合验收。现有编排成立时简要确认并引用原计划，只展开有必要调整的部分，不重抄完整映射或为形式新增里程碑/过程文档。只报文件不冲突、不报依赖条件的“可并行”不合格。小计划可合成一张短表。
+5. **总体结论与修订顺序**：建议状态、理由、与原状态的差异，先纠正前提/契约，再修设计、映射与编排；写清解除阻塞的可观察条件。
+
+### 就绪判断（沿用 dev-plan 的含义）
+
+- `Blocked`：仍有会改变范围、安全、数据、外部契约或关键 NFR 的未决项，或核心交付无法成立；说明具体阻塞范围。无关且独立的前期工作可以单列，不把整个计划宣称 Ready。
+- `Proposed`：方案与实施前置完整，只等待非阻塞评审；不能用它收纳重大未知或实质开工阻塞。
+- `Ready`：所审范围的实施前置均已解决，关键证据无缺口，剩余非阻塞建议不影响承诺交付。说明评审覆盖限制，不把 Ready 当作实现完成或产品上线许可。
+
+严重度和状态不是机械一一对应：同一个 P2 在某计划中可能阻塞关键外部契约，另一个 P2 只是非关键局部改进。依据影响判断，不使用总分平均掉阻塞项。

package/skills/review-dev-plan/references/review-lenses.md

@@ -0,0 +1,82 @@
+# 四个审查视角
+
+各 reviewer 只需读自己的节；跨视角追问时再读关联节。检查深度与计划改动面相称，不为填清单创造需求或阻塞。
+
+## A. facts：代码事实、正确性与矛盾
+
+把关键陈述整理成“计划主张 → 类型 → 来源 → 核实结果”。优先核实会改变技术选择、依赖或交付结果的事实：
+
+- 声称存在或可复用的路径、符号、路由、表、包导出、命令、配置是否真实存在；新增项明确标注即可，不能要求它已存在。
+- 追到调用者与实现的行为：参数/返回、错误、分页、排序、事务、幂等、权限传播、缓存失效和删除语义。函数同名、类型匹配不等于行为满足。
+- 安装/初始化、存量升级、部署配置和生产执行链是否与开发态假设一致。计划声明“无需改动”的邻接面是否真的支持目标。
+- 数字与结论是否有用户要求、代码、配置、运行证据或明确决策来源；没有来源的性能承诺、规模、工期不能成为架构依据。
+- 对照全文的范围/非目标、契约字段、事实归属、鉴权、数据生命周期、失败语义、迁移回滚、验收断言和进度，找互斥陈述。矛盾同时定位两处，并说明在什么操作上无法同时成立。
+- 旧文档与当前代码不一致时标明时间和基线；规则约束与运行事实分开，不能因为文档旧就自行废除规则。已有缺陷只有被本计划依赖或放大、导致目标无法交付时才进入本次 findings，并说明关联。
+
+交回关键核实表：`主张/计划定位 | 事实/设计/假设/目标 | 证据定位 | 已核实足够/已核实缺口/未核实 | 影响`。无关事实不用穷举。
+
+## B. architecture：技术先进性与可行性
+
+“先进性”评价的是在真实约束下能否改善交付、性能、安全、可靠性或维护成本。**新技术不自动加分，旧技术也不自动合格**。
+
+1. 从本期 R/NFR/C 推导需要解决的问题。主要选择是否有可行备选、收益与代价；复杂或难回退选择是否记录选择理由与重审条件。简单可逆决策无需硬补 ADR。
+2. 同时比较沿用现有范式和有实际收益的现代方案：能力差距、生态支持、复杂度、可维护性、迁移成本、运行成本和团队可操作性。仅因版本旧而建议升级不算问题；已有方案无法满足受支持版本、必要能力或明确约束时应指出。
+3. 涉及版本能力、弃用、支持周期、安全公告或外部服务限制等时效性事实，先读目标项目依赖/锁文件，再查官方文档、发布说明或原始论文，标记版本、查询日期和 URL。不能联网则列具体待核实项，不用记忆冒充最新结论。
+4. 审查模块边界、事实所有权、接口深度和变化局部性；新基础设施或抽象是否解决真实复杂度，删除它后是否只减少转发层。避免为假想规模过度设计，也不机械维护已不适配的现状。
+5. 核对关键请求/任务的并发、原子性、幂等、重试、超时、租约、隔离、背压和失败恢复，按实际风险裁剪；热路径的查询/索引、缓存与新鲜性是否满足目标。
+6. 对持久化和外部契约检查新旧版本共存、迁移/回填、切换门、不可逆步骤、回滚及恢复。对外依赖核实真实能力、权限、配额和部署条件。
+7. 验证方案能否以目标仓的构建、测试和运行入口落地；风险是否有观测/验证手段。需要 spike 的未知项写“验证问题、成功判据、影响的决策、最晚完成点”，不在评审中自动实现 spike。
+
+交回少量关键决策的判断：`选择 | 驱动需求 | 证据与版本 | 收益/代价 | 可行性 | 必要修订或保留理由`。只是另一种同样可行的做法放非阻塞建议，不能当缺陷。
+
+## C. schedule：映射、依赖与实施编排
+
+双向追踪，不只看里程碑标题齐不齐：
+
+`需求 R/NFR/C/A → 设计/决策 → 交付物/任务 → 里程碑 → 可观察验收`
+
+- 每条本期需求有实现与验收；每项设计/交付物有负责的任务；每个验收有设计依据。映射在账本或专门表中完整保留一份即可，需求原文和断言可引用 PRD/检查 ID，须追到定义与覆盖范围，不要求多处重复展开。排除/延期有明确去向，不能用无关测试占位。
+- 里程碑退出条件能判定局部结果，阶段收口有跨模块集成与用户主路径验证。允许同能力、同环境且无独立风险门的验收合并，核对检查覆盖、执行时点、收口负责人和前置就绪；骨架阶段不要求尚未实现的端到端路径。安全、迁移、不可逆操作、发布及用户分期门不能被合并绕过，风险不能拖到终验才发现。局部完成不等于阶段/跨期需求已验收，fixture 或构建通过不能替代真实集成、权限、业务或界面验收。
+- 完成数、最近完成、下一步、记录链接及基线一致；初稿不预填完成，进行中不计完成。已完成有本里程碑退出检查证据；可按测试组覆盖多条条件，须逐条可追溯，共同环境/基线可只写一次，不默认要求子任务文档。复用证据须有原记录及依据：相关代码、配置、依赖、输入与环境未变，否则重跑受影响检查，阶段收口仍有必要集成回归。适用 dev-plan 协议时核对逐行退出条件及里程碑记录，不机械否定历史格式。
+- 提取有向依赖边 `前置任务 → 后置任务` 及其产物；检查循环、缺失节点、倒置、隐藏的跨系统前置和过粗的里程碑阻塞。编号不是依赖，文件分目录也不代表无依赖。
+- 区分开发、集成和终验前置，以及代码、契约、迁移、配置/权限与环境资源依赖。下游只需某个已通过必要检查的成果时，建议将依赖细化到该成果与解锁证据即可，不强制新增里程碑。稳定契约下可用 fixture 开发；无关走查或发布排练不默认阻塞开发，用户分期与风险门仍须遵守。
+
+无论有无 findings，都交回编排核对结论；现有编排成立时引用原计划的依赖与验收安排，有必要调整时再给建议（简单线性计划可用短表）：
+
+| 波次/任务 | 前置及解锁证据 | 可同时做的工作 | 写入边界/共享负责人 | 运行资源约束 | 汇合验收 |
+| --- | --- | --- | --- | --- | --- |
+
+只有输入稳定、前置满足、文件及运行资源无冲突时才建议并行；小任务委派成本可能高于收益，未使用 subagents 本身不构成编排缺陷。公共类型、路由注册、锁文件、迁移序号由单一负责人处理；同库迁移、端口、开发栈、浏览器会话需隔离或串行。主集成人负责整体验收与计划回写。
+
+没有工期估算时只说拓扑顺序和结构上的瓶颈链；不要声称计算出关键工期或编造“节省 X%”。不能安全并行时解释具体依赖即可。reviewer 这里只建议实施编排，不启动实施任务。
+
+## D. delivery：可用性与 UI/UX
+
+从目标使用者的完整任务反推交付，避免只检查文件是否齐全：
+
+`获得/安装 → 初始化/配置 → 登录与授权 → 找到入口 → 完成核心操作 → 确认结果 → 失败后恢复`
+
+非 UI 交付使用相应旅程：调用方接入 API、运维部署服务、开发者安装并调用 SDK。没有界面时 UI 标为“不适用”，仍须审交付可用性。
+
+- 交付物是否包含所需产物、入口、配置、迁移、权限/种子增量、示例或使用说明；安装后能否实际使用，已安装用户能否升级。
+- 主路径与失败/边界是否端到端闭环；长任务、部分成功、重复提交、权限不足、依赖不可用是否给出可理解状态和恢复办法。
+- 发布顺序、回退/补偿、观测和运维步骤是否能由目标操作者执行，验证所需账号、数据、环境和工具是否在计划中有获取办法。
+- 看似“最终验收”的内容是否只覆盖单模块或静态检查；成功结果是否能由使用者观察，而不是依赖实现者知道内部日志。
+
+涉及 UI 时读取适用的 PRODUCT/DESIGN 或等价上下文，按仓库规则使用设计 skill，核对：
+
+- 信息架构、导航和发现性是否贴近目标角色与任务；主操作和信息层级是否明确，是否把实现细节变成用户的额外工作。
+- loading、empty、error、partial、disabled、success 的语义和下一步；表单校验、操作反馈、可恢复性；破坏性操作采用与后果相称的确认或撤销。
+- 权限变化、长文本/大数据、响应式、键盘与焦点、读屏名称、对比度、主题、语言和减少动效等项目适用要求是否有方案与验收。
+- 复用组件/设计规范是否一致；不因个人审美偏好报缺陷。UX 问题说明“哪个角色做什么时，被什么阻碍，导致什么结果”。
+
+区分证据层级：
+
+| 现有材料 | 能得出的结论 | 报告措辞 |
+| --- | --- | --- |
+| 仅计划/流程描述 | 任务闭环与交互方案的合理性 | 文档推演；待实现后浏览器验收 |
+| 静态设计稿/截图 | 可见布局与信息层级 | 静态评审，不能证明交互行为 |
+| 可运行原型/页面 | 本次实际走过的主路径与边界 | 写环境、步骤、结果和证据 |
+| 环境或浏览器不可用 | 只能判断已有材料 | 未在浏览器验证；注明缺口 |
+
+已有可运行 UI 且授权与工具允许时，按项目浏览器工作流验证主路径及关键边界；有写入副作用的操作先确认授权范围，不能为评审改动真实业务数据。尚未实现的计划不因没有页面就自动 Blocked，关键在交互方案与未来验收是否足够明确。类型检查和单测不算 UI 验证。

package/skills/review-prd/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: review-prd
+description: 评审既有 PRD 或产品需求文档，核实代码现状与依赖，审查创新性、先进性、可用性、便捷体验、美观 UI、AI 赋能、SMAR、UAT 预期状态及分期终验，默认将完整评审报告落盘。用户要求 review-prd、review PRD、需求评审或检查需求是否合理且可验收时使用；不用于从零写 PRD、评审技术开发计划或仅审查代码 diff。
+---
+
+# review-prd · 基于代码事实的产品需求评审
+
+目标是判断：**在用户约束内，这份 PRD 是否充分设计了值得做、可用且体验好的产品，能否清楚交接「做什么」与「怎样算完成」，它对代码现状和前置能力的认识是否真实。** 评审既检查错误与缺口，也检查有价值的创新和 AI 机会是否被遗漏；不止审文档格式。
+
+**默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和实际文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。**
+
+`references/` 相对本文件解析。仓库规则、产品上下文、代码位置、工具和外部依赖在运行时读取，不硬编码目标仓的业务约定。回复语言跟随用户。
+
+## 边界与参考
+
+- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入仅限独立评审报告；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
+- 区分**现状事实、目标能力、用户/平台约束、未证实假设、验收门槛与观察/PoC 基线**。新能力尚未实现不是 PRD 缺陷；代码当前行为也不是禁止产品演进的理由。报告指出增量与前置，不擅自把当前实现固化为需求。
+- PRD 回答 what / why / 怎样算完成。用户旅程、信息层级、视觉要求、AI 产品行为属于产品设计；内部架构、表结构、端点拆分、模型/算法选型与技术里程碑属于开发计划。UAT 定义角色、场景、预期状态与清晰判据；测试脚本、造数、故障注入、工具及 TC 创建属于测试计划。已给定技术约束、外部产品契约与作为产品能力的评测台可以保留，不能机械按技术词判越界。
+- 在可用时读取 `prd/references/product-quality.md` 校准产品质量规则；采用该模板的文档再按需读 `prd/references/prd-skeleton.md`。找不到 `prd` 时继续按本技能的实质标准评审，不要求安装依赖。用户自定义模板或历史 PRD 不因章节名、编号、缺少 TC 或未录入 SPMS 被判不合格。
+- UI 评审读取目标仓实际适用的产品/设计规范；只有能看到的材料才支持视觉结论。源码、静态稿、原型与浏览器实测分别标注，不把静态推演写成已验证体验。
+
+## 1. 锚定输入与审查基线
+
+1. 定位用户指定 PRD、原始诉求、已确认约束、关联 PRD 与必要决策。目标无法唯一确定时询问文件/范围，可以先调查仓库规则；不擅自选一份相邻文档评审。
+2. 读取适用的根目录及相关子目录规则、产品与设计上下文。记录 PRD 路径/版本或内容 hash、调查日期、代码仓路径、commit 与 dirty 状态；当前工作树参与调查时明确写出。无 Git 则用可用版本标识；读不到源代码则如实记录证据缺口，继续能做的文档审查。
+3. 提取目标、非目标、角色/权限、业务状态、关键旅程、FR/NFR、UAT/验收、依赖、产品决策、分期与终验关系。无需求 ID 时用稳定章节定位，不补造 SPMS key。只读工具可用时核对关联项目/需求与重复立项情况，不把录入状态当实现状态。
+4. 将会改变产品选择的现状主张和前置条件列入核实清单：声称已支持、未支持、可复用、无需改动、兼容、已验证及性能数字等。标清它们是事实还是未来目标。
+5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径；记录四个审查维度及代码核实、报告写入、回读核验的状态。事实能查就先查，只向用户询问无法从证据推出的产品决定；缺少某项输入时继续不依赖它的审查。
+
+## 2. 编排四个审查视角
+
+先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派。各视角都以用户约束为边界，不为凑问题扩大产品范围。
+
+| 角色 | 主责 | 必须交回的专属结果 |
+| --- | --- | --- |
+| `facts` | 代码现状、依赖契约、主张真伪与内部冲突 | 现状核实矩阵：已有能力、真实增量、行为冲突、未核实项及证据 |
+| `product` | 创新、先进性、AI 价值与合理范围 | 关键产品选择的价值/取舍；有依据的遗漏机会、AI 闭环与前置 |
+| `experience` | 可用性、便捷旅程、美观 UI 与状态表达 | 各角色任务闭环；体验/视觉缺口；界面证据等级 |
+| `acceptance` | SMAR、UAT、需求追踪、分期与终验 | 目标/场景/需求/验收/UAT 的断链；独立用户价值、计划规模与终验一致性 |
+
+### 调度规则
+
+- 有多 agent 工具且当前授权允许时实际启动只读 subagents，主 agent 负责综合裁定和报告单写；不能在同一回答中扮演多个角色后宣称独立复核。简单局部文档可用两位 reviewer 各覆盖两个视角，回报分开说明覆盖与结论。模型继承主 agent，不主动覆盖模型或推理档位。
+- 并发数按实际剩余槽位安排，主 agent 也占槽位。只有 4 个总槽位时，先运行 3 个视角，结束后复用空闲 agent 完成第 4 个；更少则分批。工具/授权不允许、用户要求串行时，主 agent 按四个视角顺序审查，如实写执行方式，不能漏掉维度。
+- 初轮给 reviewer 相同基线、用户约束和原始材料，不把预设缺陷或别人的结论当答案。每个 reviewer 只读原 PRD 与代码，不能继续派生 agent，也不写最终报告。
+- 代码可并行只读；共用浏览器或外部环境由一个操作者采集证据。评审不自动跑迁移、种子、部署、收费模型评测或有副作用的业务操作。必要验证按现有授权执行，做不到则报告缺口。
+- 单个 reviewer 失败时重派一次或由主 agent 接管；不能核实的部分进入待核实项，不无限重试。
+
+### Reviewer 派发合同
+
+```text
+你负责 {facts/product/experience/acceptance}，只读评审，不实现、不改稿、不继续派生 agent。
+用户目标及范围：{原始要求、排除、已有产品决定}
+PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日期}
+必读：{本 SKILL.md、report-contract.md、review-lenses.md 对应节的绝对路径}
+相关材料：{规则、产品/设计上下文、已知代码入口、关联 PRD/需求的实际位置}
+资源边界：{可读目录、可运行检查、外部查询与浏览器授权}
+核实产品主张依赖的实际行为；新功能未实现不算缺陷，现有代码也不是永久产品约束。
+交回：范围与基线；候选问题（PRD 定位、场景/触发、影响、证据、最小产品修订、
+复核判据、严重度与置信度）；本视角专属结果；待核实/待决定项及所需证据。
+没有问题可以返回空 findings。机会提案须说明用户价值与约束，不强制增加功能或实现方案。
+```
+
+## 3. 主 agent 交叉复核与裁定
+
+1. 逐条阅读支持候选问题的 PRD 段落与原始证据，核对角色、作用域、版本和触发条件。文件/函数存在不等于行为可用，多位 reviewer 一致也不等于事实。
+2. 现状核实至少追到 PRD 依赖的用户或外部系统可观察行为：入口/权限、关键业务逻辑、结果与状态反馈；按需求核对租户隔离、分页、重复/冲突、数据保护、失败恢复、AI 权限/预算及依赖。只读到部分链路就标部分核实，不声称端到端可用。
+3. 将证据影响传回相关视角：例如事实侧发现模型调用没有当前主体授权，产品侧复核 AI 前置，体验侧复核不可用状态，验收侧复核判据和分期。只复核受影响链路，不借机设计具体调用方案。
+4. 按根因与修订动作去重，保留所有实质不同的问题。已确认问题进入 findings，低证据主张进入待核实项；纯偏好不算缺陷，有价值但非必要的产品机会单列，不凑问题数或用总分抵消阻塞。
+5. 核对「目标 ↔ 场景 ↔ FR/NFR ↔ 验收 ↔ UAT 状态 ↔ 分期/终验」的一致性。每期要有独立用户价值；承接计划尽量 5–8 个 Milestone，连续性例外 9–10 个须有理由，最多 10 个。PRD 的规模建议不是技术任务表，不能要求其已经拆出 M1…Mn。
+6. 结束前核对 PRD 与相关代码是否并发变化；只重审受影响结论，无法收敛则标待核实。收集或停止仍在运行的 reviewer，再交付。
+
+## 4. 输出评审结果
+
+使用 [references/report-contract.md](references/report-contract.md) 的完整报告顺序和落盘合同，**先列问题，再给总体结论与修订顺序**。由主 agent 保存完整报告并回读；空 findings、代码无法访问或结论为「需补证」也要落盘。
+
+报告至少包含：
+
+- 按严重度排序且可定位的问题，附用户场景、实际后果、行为级证据、最小产品修订与复核条件。
+- 代码现状核实矩阵、关键依赖和待核实项；区分静态代码、现有测试、实际运行与浏览器证据，不把尚待开发的目标报成当前缺陷。
+- 四维覆盖及六个产品设计维度的实质结论、SMAR/UAT 与分期终验的断链；不因缺少固定章节或 TC 判错。
+- 建议结论 **通过 / 需修订 / 需补证**，写清阻塞范围与解除条件；有价值的非阻塞机会与修订优先顺序。
+
+**评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、UI 已验证或可直接上线。** 最终聊天回复给实际报告链接、结论和关键问题/待核实项摘要。写入失败时说明「报告未落盘」并按合同保留完整内容，不能链接不存在的产物。

package/skills/review-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PRD 评审"
+  short_description: "核实代码现状，审查产品价值、AI、UI、UAT、SMAR 与分期，产出有证据的评审报告"
+  default_prompt: "使用 $review-prd 评审指定 PRD，核实代码现状及关键依赖，将有证据的问题、产品改进建议和结论写入完整评审报告，默认落盘并回读核验，回复报告链接与摘要。"

package/skills/review-prd/references/report-contract.md

@@ -0,0 +1,64 @@
+# 问题判定与 PRD 评审报告合同
+
+## 落盘与交付
+
+- **默认保存完整 Markdown 报告**；只有用户明确要求仅聊天或不写文件时跳过。聊天正文、拟写入内容和路径预告都不算已落盘，不把「是否保存」留作交付前的确认问题。
+- 路径优先级：用户指定 → 本地 PRD 同目录的 `<PRD 文件名去掉扩展名>.review.md`。输入只有聊天文本/远程文档时遵循仓库报告目录惯例，无惯例则写当前工作区的 `docs/reviews/<主题短名>.review.md`。按需建目录，不因未给路径停下。
+- 写入前检查同名。已授权更新/覆盖该报告则执行；否则保留旧报告，依次尝试同目录 `<主题>.review.<YYYY-MM-DD>.md`、`<主题>.review.<YYYY-MM-DD>-2.md` 等未占用名称。用户指定路径冲突也保留旧文件并说明实际路径，不覆盖原 PRD 或代码。
+- 主 agent 单写完整报告并回读实际文件，核对 findings、待核实项、代码矩阵、覆盖、映射/分期、结论和修订顺序齐全；检查引用定位与文件链接。空 findings、缺源码或「需补证」不免除落盘。
+- 最终聊天给实际报告链接、结论与关键摘要；仅聊天模式在聊天交付完整报告。写入工具不可用或失败时明确「报告未落盘」、原因与目标路径，在聊天保留完整结果，将保存标为未完成；不能链接不存在的文件。
+
+## 什么进入 findings
+
+确认的问题同时具备：PRD 可定位的主张/缺口、已核实依据、具体用户场景/触发、对已确认目标的实际后果、可执行的最小产品修订。每条一个独立根因，重复症状合并但保留关键定位。纯格式、偏好或无关旧代码问题不进入 findings。
+
+「没有写 X」先查正文、引用、附录及已确认约束，证明 X 是本产品目标的必要条件；章节标题不同不算缺失。新功能未实现不算 PRD 错误；可确认的前置误判、虚假现状或缺少产品增量才是问题。源码未定位、依赖未联调不是「能力不存在」的证据。
+
+证据不足的主张放待核实项，写需什么证据及对结论的影响；关键证据缺口仍可阻塞通过。高价值且在约束内的增强机会有依据则单列提案，不能把每个合理备选都报成缺陷，更不能借评审自行增加产品承诺。
+
+## 严重度与置信度
+
+| 等级 | PRD 评审中的含义 |
+| --- | --- |
+| P0 | 已确认的产品规则直接要求重大安全、数据或业务灾难，需立即纠正；极少使用 |
+| P1 | 核心任务、权限/数据边界、关键依赖或终验口径存在高影响错误/缺口，进入下游计划前须修订 |
+| P2 | 局部产品行为、体验、验收或分期存在可证实缺口，相关范围交接前修正 |
+| P3 | 有明确依据和收益的小改进，不阻塞交接；个人偏好不算问题 |
+
+严重度表示后果，置信度用高/中及依据表达证据强弱。仅猜测的风险不能靠降为 P3 混进 findings，不设问题数或评分指标。
+
+## 单条问题格式
+
+```markdown
+1. [P1] F-01 · <可行动的标题>
+   - 定位：<PRD 文件:行号/稳定章节；冲突时两处；需求/场景/验收 ID>
+   - 场景与问题：<什么角色在什么条件下要完成什么，按当前 PRD 会产生什么后果>
+   - 证据：<读过的代码文件:精确行号/符号、用户约束/规则定位、运行证据或官方文档 URL/版本/日期>
+   - 修订：<最小需要补定/改正的产品行为、状态、边界、前置或验收；不展开内部实现>
+   - 复核：<改稿后应一致的产品断言/依据；未来效果验证与本次文档复核分开>
+   - 置信度：<高/中 + 依据>；阻塞：<目标/需求/交接范围或否>
+```
+
+本地引用使用可点击文件链接与短行定位，必要时补稳定标题/符号；定位指向原 PRD 应承载要求的位置，不指向 reviewer 自己的新报告。只引用读过的原文，截断内容先补读；不能把外部例子数字当成本产品承诺。
+
+## 完整报告顺序
+
+1. **确认问题**：P0 → P3，F-01 等稳定编号；无确认问题如实写「未发现可确认的问题」。复审沿用编号，区分已解决、仍存在、新增。
+2. **待核实/待决策**：缺什么证据或产品决定、影响哪项需求、谁能提供及应在何交接节点前明确；负责人未知写待指定，不虚构日期或用户承诺。
+3. **代码现状核实矩阵**：`PRD 主张/定位 | 类型 | 实际行为与证据等级 | 已有满足/部分满足/真实增量/行为冲突/未核实 | 产品影响`。代码读不到仍列关键主张、调查限制和所需材料，不留空表假装核实完毕。
+4. **覆盖与基线**：PRD 版本/路径、代码仓/commit/dirty、日期、实际 reviewer 分工或串行方式、四维覆盖。六个产品维度分别给结论/不适用理由；记录实际代码、测试、设计稿及浏览器证据等级与缺口，只列结论相关来源，不倾倒读文件日志。
+5. **需求追踪与分期终验**：列目标/场景/需求/验收/UAT 断链或已核对范围；检查每期独立价值、5–8 个 Milestone 预算/最多 10 个的连续性例外、关键前置、跨期终验及相互冲突的口径。建议产品交付顺序，不生成技术任务、并行波次或测试脚本。
+6. **产品增强机会**：有依据的非必要提案，写价值、场景、约束/代价及采用后需调整的需求；无则写「无」，不为创新凑数。
+7. **总体结论与修订顺序**：建议结论、阻塞范围与解除条件。先修事实/约束，再定产品语义/体验/AI，随后同步验收、UAT 和分期终验。未解决的重大未知不能藏进「通过」。
+
+短 PRD 可以用紧凑段落/表格承载这些内容；完整报告不是固定字数，也不是 reviewer 原始回报的拼接。结构借鉴 `review-dev-plan`，判断对象是产品需求，不沿用其实施就绪状态或技术编排要求。
+
+## 结论口径
+
+- **通过**：所审范围产品目标、行为、状态、验收与分期清楚，关键现状和前置有证据，剩余建议不影响交接；说明覆盖限制。
+- **需修订**：有已确认且阻塞交接的产品问题，列具体范围和修订条件。无关独立能力可单列已满足条件，不能将整份含阻塞的 PRD 宣称通过。
+- **需补证**：暂无已确认的交接阻塞，但关键现状、依赖或产品决定仍不能成立/未确认，列所需证据与节点。已有阻塞缺陷同时存在时用「需修订」并继续列补证项。
+
+状态按影响与证据判断，不能靠总分平均。纯产品方向已经足够明确、技术实现选择留给开发计划时，不因尚无架构方案阻塞 PRD；核心依赖能力是否存在/授权/适配仍须核实。
+
+评审通过不表示功能已实现、线上部署、性能达标、UI 已通过浏览器验收，也不自动批准需求或变更 SPMS 状态。

package/skills/review-prd/references/review-lenses.md

@@ -0,0 +1,82 @@
+# 四个 PRD 审查视角
+
+Reviewer 读自己的节；跨视角复核再读关联节。按本次产品范围裁剪检查深度，不能用一张通用清单制造功能或阻塞。
+
+## A. facts：核实代码现状与前置
+
+先把关键主张分成现状、未来能力、约束、假设、验收目标。事实核实优先覆盖会改变范围、产品形态、权限、兼容、质量或依赖的陈述。
+
+### 从文件存在追到实际行为
+
+1. 用 `rg --files` / `rg` 定位声明和真实调用者，读取相关入口、授权、业务实现、返回/状态展示及必要配置。文件名、路由、类型或函数存在，只能证明那个入口存在，不能证明已经满足用户场景。
+2. 按 PRD 依赖的行为追踪：谁能发现/执行、输入边界、状态迁移、结果是否可消费、错误/降级、重复与冲突、分页与规模、跨租户/用户边界。发现对应测试时读其断言和替身，区分真实行为与 mock 假设；未执行测试不写「测试通过」。
+3. 核实可复用依赖的契约、权限、配置和目标环境：可检索不等于可安装，HTTP 入口不等于支持 Agent 原生消费，模型网关存在不等于当前应用/主体可调用，前端隐藏按钮不等于后端拒绝越权。
+4. 声称「不存在」时说明检查过的目录/入口/配置和搜索范围，必要时跟踪动态注册或外部服务。仅未搜到关键词只能写「在已查范围未定位」，不能断言整个系统没有能力。
+5. 声称已验证兼容、性能、UI 或生产可用时核对实际环境、版本与记录。当前源码存在、历史计划完成、SPMS 状态与生产部署不是同一事实。没有部署证据不推断线上版本；没有有效测量不声称达到门槛。
+6. 数字、业务规则和平台约束给来源；区分代码现状与规范要求。两者冲突就同时定位，不因代码不同自动废除约束。旧文档/README/记忆仅是线索，不代替本次行为核实。
+7. 涉及当前生态支持、版本能力或外部限制时先读依赖/配置，再查官方文档或一手来源，保留版本、日期与链接。不能访问就标具体待核实项，不以记忆冒充最新结论。
+
+### 现状核实矩阵
+
+| PRD 主张/定位 | 类型 | 代码现状及证据等级 | 与目标的关系 | 产品影响/所需补证 |
+| --- | --- | --- | --- | --- |
+| <已有能力/可复用/未支持等陈述> | <现状/目标/约束/假设> | <路径:行号/符号;源码核实/测试记录/实测/未核实> | <已有满足/部分满足/真实增量/行为冲突/未核实> | <改正背景、明确增量、补前置/决策/证据> |
+
+「真实增量」仅表示本次已查实现不具备目标能力，不表示 PRD 有缺陷。「已有满足」也不自动撤回需求，可能仍需要新的可用性、质量或治理边界。用户已明确不考虑存量时尊重该选择，不强加迁移兼容；其他产品前置仍须核实。
+
+已有代码缺陷只有被本 PRD 依赖、放大或直接阻断目标时进入评审；无关代码问题不扩展成本次代码审计。源码不可访问时交付明确的核实清单与证据缺口，继续其他维度；不能冒充已核实或直接判依赖不存在。
+
+## B. product：创新、先进性、AI 与范围
+
+从用户问题推导价值，检查采用的选择是否在约束内把任务设计充分。先进性以用户收益、质量和合理成本判断，技术新旧、术语数量或功能多少不自动加分。
+
+- 是否仅转录功能清单，遗漏完成关键任务必须的发现、理解、决策、使用与维护环节？是否有比照搬现状/参考项目更有价值的产品形态？指出具体场景、收益与取舍，不能只写「不够创新」。
+- 参考产品、官方生态能力是否适配目标用户、租户、身份和使用环境？区分声明、已核实能力和拟新增能力，避免承诺未经验证的兼容组合。
+- AI 能改善发现、理解、创作、决策或重复劳动时是否有合理方案？未采用但有充分理由则可接受；没有 AI 不自动算缺陷，用户排除或价值不足时不强加。
+- 已采用 AI 是否有明确任务、触发、授权输入、可用输出、依据/不确定性、用户采纳/修改/拒绝/撤销、质量口径、成本与不可用状态？辅助 AI 不可用时基本任务能否继续；AI 是核心时是否如实进入等待/失败，而非虚假成功？
+- 原始诉求、目标、范围、非目标及决策是否一致？终局是在本 PRD 范围内充分设计，不是整个产品无限扩张。PoC 说明要证明的假设及成立判据，不能自动扩成完整系列，也不能仅罗列技术组件。
+- 是否把怎么实现混进产品决策？内部架构、表/端点设计、算法/模型选型移交开发计划；已给定约束和外部可消费契约保留必要产品语义。
+
+交回：`产品选择 | 用户价值/目标 | 依据与约束 | 取舍/不足 | 必要修订或非阻塞机会`。遗漏机会只有在直接影响已确认目标、且收益和适配有依据时才作为缺陷；其他合理改进单列提案，不能未经确认写成承诺。
+
+## C. experience：可用、便捷与美观 UI
+
+逐角色走主旅程：`找到入口 → 理解信息/条件 → 完成任务 → 确认结果 → 再次使用或失败恢复`。无 UI 产品仍走调用方/Agent/运维的相应消费旅程，可用性不能随 UI 一起跳过。
+
+- 主路径是否能完成端到端任务，而不是只有数据、API 或几个按钮？用户是否被迫理解内部术语、反复输入信息、切换入口或自行补步骤？首次与高频路径是否合适？
+- 相关的等待、空数据、无权、错误、部分成功、重复/冲突、取消及恢复是否状态清楚、结果真实、下一步可行动？角色与权限改变不能只靠前端隐藏。
+- 默认信息、主操作和信息层级是否支持任务；细节是否渐进展示；风险和必要前置是否始终足够可见？
+- 美观是否落实为信息主次、排版、密度、留白、视觉语言与宿主一致性；是否只写「现代 UI」或仅有可访问性指标？适用的窗口、主题、语言、键盘/焦点、对比度等是否有产品要求与验收？
+- 区分产品交互与实现：一次引用跳转、状态反馈、可撤销操作属于 PRD；组件库、CSS/DOM 与焦点代码的实现不应被强制补进 PRD。
+
+| 实际材料 | 支持的结论 | 必须说明的限制 |
+| --- | --- | --- |
+| PRD/流程/源码 | 任务闭环、规则与交互要求的合理性 | 文档/静态代码推演，不能证明美观或真实交互通过 |
+| 设计稿/截图 | 可见布局、信息层级与视觉一致性 | 静态评审，不能证明操作和权限行为 |
+| 已授权的原型/浏览器实测 | 本次实际观察的旅程、状态与视觉 | 记录环境/版本/场景/结果；没有走过的路径仍未验证 |
+
+没有实现页面不自动阻塞 PRD；关键在产品状态与验收是否已定清。现有页面可安全只读走查时按目标仓浏览器工作流采集证据，不为评审改动真实业务数据。UX findings 写清哪个角色在什么任务中被怎样阻碍，不能把个人审美偏好当缺陷。
+
+## D. acceptance：SMAR、UAT 与分期终验
+
+SMAR 检查目标与需求：
+
+| 原则 | 核对要点 |
+| --- | --- |
+| Specific | 角色、对象、场景、作用域、权限与能力边界明确，领域词和状态语义一致 |
+| Measurable | 预期状态可判断；数值有作用域/负载/样本/分母/窗口，明确枚举、是/否、相等/不变也合格 |
+| Actionable | 用户或授权主体能执行具体业务动作，得到可用结果；不只写愿景或技术名词 |
+| Reasonable | 价值、质量、成本、依赖及支持范围与用户约束相容，未知前置没有被写成无条件承诺 |
+
+区分验收门槛、上线观察指标与 PoC 比较基线；建议数值不能冒充已实测结果。不用 Time-bound 编造工期，已有外部日期、性能时延、超时、有效期及观察窗口仍有效。
+
+双向追踪：`原始诉求/目标 → 场景 → FR/NFR → 验收 → UAT 预期状态 → 分期/终验`。
+
+- 每个目标有需求承接，每个重要用户场景有预期状态与通过条件，每条完整能力有可判断的验收。UAT 应描述结果是否可用、反馈、下一步及数据变化，不只是一条提示文案。
+- 成功与本产品相关的空、拒绝、冲突、取消、失败/恢复和 AI 不确定/降级场景有清晰结果。不能到测试计划阶段才决定产品状态，也不能把造数、脚本、探针、故障注入当 UAT 内容。
+- 没有 TC、没有 SPMS key、章节不同本身不算缺陷。真实 key 不可伪造；缺少验收语义才是问题。代码/设计内部断言若无法表达外部结果，要求改为业务边界，不要求 PRD 拟写测试过程。
+- 每期有独立用户价值、范围与出口判据，不按前后端技术栈切期。终局需求不因交付节奏被删小，非目标不充当延期列表；已明确的其他 PRD 分工可作为范围去向。
+- 每期开发计划尽量 5–8 个 Milestone；连续性例外 9–10 个说明理由，最多 10 个；小范围可以更少，不凑数。这里只检查规模预算，详细任务和准确拆解由 dev-plan 核实，超出则反馈拆期。
+- 逐条核对分期验收分配和最终完成期；跨期条目正文、分期矩阵及已录入系统的终验声明口径一致。部分交付不能被标成整条完成，前置条件不归本 PRD 的不得被默默视为已就绪。
+
+交回断链 ID/章节、相互矛盾的两处、受影响用户场景与最小产品修订。不能因没有开发计划的技术里程碑而判 PRD 不可行动。

package/skills/review-prd-dev-gaps/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: review-prd-dev-gaps
+description: 接受 PRD 与已完成的开发计划，追读里程碑完成记录并核对实际实现，将差异分为明确遗漏、合理变更和需用户 Triage 的实现差异；通过交互式问答确定处置，有 follow-up 时调用 dev-plan 创建 gaps plan。用于开发完成后的需求覆盖核查，不用于评审 PRD 质量、计划设计或单次代码 diff。
+---
+
+# review-prd-dev-gaps · PRD 与开发交付差异核查
+
+目标：回答 **PRD 要求的能力实际上交付了什么，哪些漏做了，哪些调整有充分依据，哪些差异需要用户拍板，以及还要补什么。** 以 PRD 建立完整覆盖账本，以计划、完成记录和实际行为交叉核实，不把「计划已完成」等同于「PRD 已实现」。
+
+默认交付完整差异报告；存在应跟进事项时，再实际调用 `dev-plan` 产出独立 gaps plan。`references/` 相对本文件解析，回复语言跟随用户。
+
+## 边界
+
+- 输入为 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](references/report-contract.md)，确定报告路径，建立 `PRD → 计划/里程碑 → 完成记录 → 实际行为/验证` 的追踪账本。**从 PRD 向下追踪**，防止只审计划已有条目而漏掉从未进入计划的需求。
+
+## 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」，不创建空计划。
+- 清单非空时，**实际定位并读取可用的 `dev-plan/SKILL.md`，按其写计划流程、骨架和校验生成独立 gaps plan**；不止建议用户以后调用，也不在本技能复制一套开发计划模板。缺少该技能时查找可用安装位置；仍找不到则保留报告和交接清单，说明计划生成受阻，不能声称已创建。
+- 交给 `dev-plan` 的输入：PRD、原计划及相关记录路径，差异报告、代码基线，选定 G-ID 和 D-ID，已确定目标与验收、排除/延期项、相关代码证据和依赖。原 PRD 提供来源，用户确认的变更提供新目标，当前代码提供起点；不能让下游再次按旧 PRD 推翻已确认决定。
+- 使用 `<原计划名>-gaps` 作为默认代号，输出目录、重名处理和最终状态遵守 `dev-plan`。保留 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 已完整交付。