prd-review

Purpose

PRD 交付开发前的质量关卡。解决的核心问题：需求文档终稿质量不稳定，缺乏统一验收标准，导致开发频繁返工。

像一个严谨的需求评审官——逐模块检查 PRD 是否完整、自洽，并结合知识库（优先 coding-knowledge/business/prd-reference/，兼容 prd-knowledge/）判断新需求是否与现有系统冲突。输出结构化报告，标明阻塞/建议/提示三级问题，每条附修改建议。修改后再跑一次，直到阻塞清零。

输入

用户提供 PRD 文件路径（Markdown 格式）。PRD 应包含以下 7 个模块：

模块	内容
需求背景	需求来源、上下文、触发原因
需求价值	业务目标、用户收益、量化成功指标
功能清单	功能列表，含优先级
业务流程图	核心操作流程（通常用 Mermaid）
数据模型	涉及的实体、字段、关系
需求详情	每个功能的详细描述、交互说明、验收标准
权限管理	角色权限矩阵、操作权限说明

如果 PRD 结构与上述不完全一致，按内容语义映射到最接近的模块检查。

工作流程

Step 1: 读取 PRD 和知识库

1. 读取用户指定的 PRD 文件，提取 YAML frontmatter 中的 version 和 module 字段（如有），用于报告中标注检查的版本
2. 根据 PRD 文件所在目录确定业务模块名（通常是 requirements/{模块名}/prd-draft.md），检查报告将输出到同目录下的 review/ 子目录
3. 按以下优先级查找 PRD 知识库：
   • 优先：coding-knowledge/business/prd-reference/ 目录（与编码知识库集成）
   • 兼容：prd-knowledge/ 目录（独立知识库）
4. 如果存在知识库，读取以下文件用于交叉校验：
   • existing-features.md — 校验功能是否重复
   • user-roles.md — 校验权限体系一致性
   • business-flows.md — 校验业务流程衔接
   • glossary.md — 校验术语一致性（读"业务定义"部分）
   • data-model.md — 校验数据模型冲突（仅 prd-knowledge/ 路径下存在时读取）
   • api-inventory.md — 校验是否遗漏对现有接口的影响（仅 prd-knowledge/ 路径下存在时读取）
5. 如果两个路径均不存在知识库，仅做文档自身完整性检查，在报告中提示建议先运行 knowledge-init 或 coding-knowledge-init
6. 检查 PRD 同目录下是否存在 prd-context.md（需求决策基线）。如存在，读取其中的"需求决策"和"业务事实"，用于 2.8 需求上下文一致性校验

Step 2: 逐模块检查

对每个模块按以下维度审查。每发现一个问题，记录问题描述、严重程度、修改建议、知识库依据（如有）。

特别注意跨模块一致性——功能清单里有的功能，需求详情里必须有对应描述；业务流程图里的角色，权限管理里必须有定义。这类交叉不一致往往是最有价值的发现。

2.1 需求背景

• 背景是否清晰（需求从哪来？谁提出的？什么场景触发？）
• 问题是否有依据（数据、用户反馈、竞品分析，而不是"我觉得"）
• 范围是否界定（本次做什么、不做什么）

2.2 需求价值

• 业务目标是否量化（转化率提升 X%、效率提升 X 分钟等可衡量指标）
• 用户收益是否具体（对谁有什么好处，有场景说明）
• 优先级是否合理（投入产出比是否说得通）

2.3 功能清单

• 功能是否完整（结合业务流程看，有没有遗漏）
• 优先级是否标注（P0/P1/P2 或类似标记）
• 与现有功能是否重复（对照知识库 existing-features.md）
• 功能边界是否清晰（不会产生歧义）

2.4 业务流程图

• 主流程是否完整（从起点到终点，正常路径走得通）
• 异常分支是否覆盖（失败、超时、取消、驳回等）
• 角色是否标注（每个操作节点由谁执行）
• 与现有流程是否衔接（对照知识库 business-flows.md）
• 状态流转是否完整（所有可能的状态转换）
• 判断分支与需求详情一致（流程图中每个判断分支的规则是否与对应 F-XX 需求详情中的约束描述一致，如流程图允许删除上线视频但 F-XX 约束说仅下线可删除，则标 🔴）

2.5 数据模型

• 实体是否完整（功能清单中的对象都有对应实体定义）
• 字段是否充分（类型、长度、约束是否定义清楚）
• 关系是否明确（一对多、多对多等关联关系）
• 与现有模型是否冲突（对照知识库 data-model.md）
• 枚举值是否列全（状态、类型等字段的可选值）

2.6 需求详情

• 交互说明是否清晰（页面布局、操作流程、反馈方式）
• 验收标准是否可测（可验证的验收条件）
• 边界条件是否定义（最大值、最小值、空值、特殊字符）
• 错误处理是否覆盖（出错场景的提示和处理方式）
• 术语是否一致（对照知识库 glossary.md 的"业务定义"部分）
• 产品导向检查：PRD 全文是否包含代码实现细节（类名、方法名、表名、字段名、服务代号等）。PRD 的读者包括业务方和法务，不能出现 SealHandlerServiceImpl、t_e_contract、genSealStrategyJson() 这类代码层面的内容。如果发现，标为"建议"并给出产品语言的替换写法

2.7 权限管理

• 角色是否完整（涉及的所有用户角色列全）
• 权限矩阵是否清晰（每个角色对每个功能的操作权限：查看/编辑/删除/审批）
• 与现有角色体系是否一致（对照知识库 user-roles.md）
• 数据权限是否考虑（数据可见范围：只看自己的 vs 看全部）
• 特殊场景是否覆盖（角色变更、权限继承、临时授权）

2.8 需求上下文一致性（双向校验）

如果 PRD 同目录下存在 prd-context.md（由 prd-draft 自动生成的需求决策基线），执行双向一致性校验。prd-context 中的"需求决策"是用户做出的选择（本可以选别的方案），"业务事实"是客观约束——两者的校验逻辑不同。

Context → PRD 方向（决策是否落地、事实是否矛盾）：

• 需求决策：逐条检查是否在 PRD 正文中体现（功能清单、需求详情、数据模型、流程图等章节）
  • 决策在 PRD 中找不到对应描述 → 🔴 阻塞："需求决策未落地"
  • 决策与 PRD 描述矛盾（如 context 说"两级审核"但 PRD 写了"一级审核"）→ 🔴 阻塞："PRD 与需求决策矛盾"
• 业务事实：检查 PRD 是否与事实矛盾（不要求每条都出现在正文中）
  • PRD 描述与业务事实矛盾（如 context 说"最多 50 个签章位"但 PRD 未设上限）→ 🟡 建议："PRD 与业务事实不一致"

PRD → Context 方向（重要决策是否收录）：

• 扫描 PRD 中的关键决策点：数据模型的核心字段设计、流程中的分支规则、权限矩阵中的特殊限制、验收标准中的量化指标
• 判断标准：这个决策点"用户本可以选别的方案吗？"——如果是，且 context 中没有对应记录，标为 🟡 建议："建议将此决策补录到 prd-context.md"
• 这个方向不标阻塞，因为 context 可能是早期版本、还没来得及同步

不存在 prd-context.md 时：

• 标为 🟡 建议："建议通过 prd-draft 生成 prd-context.md 作为需求决策基线，便于后续修改和评审时追溯用户确认的决策"
• 不阻塞，因为手写的 PRD 可能没有走 prd-draft 流程

Step 3: 生成检查报告

在 PRD 文件所在的业务模块目录下创建 review/ 子目录，按章节名输出：

requirements/{模块名}/
├── prd-draft.md                    ← prd-draft 产出的草稿
└── review/                         ← 本 skill 产出的检查报告
    ├── review-summary.md           ← 总览报告
    ├── 需求背景.md
    ├── 需求价值.md
    ├── 功能清单.md
    ├── 业务流程图.md
    ├── 数据模型.md
    ├── 需求详情.md
    ├── 权限管理.md
    └── 需求上下文一致性.md

单模块报告格式

# {章节名} 检查报告

> PRD 文件: {文件路径}
> PRD 版本: {从 YAML frontmatter 的 version 字段读取，如 draft-v1；如无则标注"未标注"}
> 检查时间: {timestamp}
> 知识库: {已加载 / 未找到}

## 检查结果统计

| 严重程度 | 数量 |
|----------|------|
| 🔴 阻塞 | X |
| 🟡 建议 | X |
| 🔵 提示 | X |

---

## 🔴 阻塞问题

阻塞意味着 PRD 在当前状态下不应进入开发，必须先修复。

### [B-01] {问题标题}

**问题描述：** {具体哪里有问题}

**影响范围：** {不修复会导致什么后果}

**修改建议：** {具体应该怎么改}

**知识库依据：** {引用 prd-knowledge/ 中的内容，如无则标注"文档自检"}

---

## 🟡 建议问题

不阻塞交付，但修复后能显著提升需求质量。

### [S-01] {问题标题}

**问题描述：** {具体说明}

**修改建议：** {建议怎么改}

---

## 🔵 提示信息

优化建议，可选择性采纳。

### [T-01] {问题标题}

**说明：** {补充信息或优化方向}

---

## 检查通过项

{列出该模块中检查通过的项目，让作者知道哪些部分没问题}

问题严重程度定义

准确分级是这个 skill 的核心价值——过多"阻塞"让作者疲于应付，过少起不到把关作用。

级别	定义	判断标准
🔴 阻塞	缺失关键信息，开发无法开工或极大概率返工	开发看到会说"这块怎么做？我得找 PM 确认"
🟡 建议	信息不够完善，开发能做但容易理解偏差	开发看到会说"大概知道怎么做，但细节不太确定"
🔵 提示	可以更好，但不影响开发理解和执行	开发不会有疑惑，只是"写得更规范就更好了"

典型阻塞场景：功能清单缺核心功能、没有验收标准、数据模型与现有系统矛盾、权限遗漏关键角色。

典型建议场景：异常流程未覆盖、边界条件未定义、术语不一致、优先级未标注。

典型提示场景：措辞可更清晰、建议补充示例图、建议统一格式。

总览报告 (review-summary.md)

# PRD 完整性检查总览

> PRD 文件: {文件路径}
> PRD 版本: {从 YAML frontmatter 的 version 字段读取，如 draft-v1；如无则标注"未标注"}
> 检查时间: {timestamp}
> 知识库: {已加载 / 未找到}

## 总体评估

| 维度 | 状态 |
|------|------|
| 是否可交付开发 | ✅ 可以 / ❌ 不可以（存在 X 个阻塞问题） |
| 阻塞问题 | X 个 |
| 建议问题 | X 个 |
| 提示信息 | X 个 |

## 各模块状态

| 模块 | 阻塞 | 建议 | 提示 | 状态 |
|------|------|------|------|------|
| 需求背景 | 0 | 1 | 0 | ✅ |
| 需求价值 | 1 | 0 | 1 | ❌ |
| 功能清单 | 0 | 2 | 0 | ✅ |
| 业务流程图 | 0 | 0 | 1 | ✅ |
| 数据模型 | 1 | 1 | 0 | ❌ |
| 需求详情 | 0 | 1 | 2 | ✅ |
| 权限管理 | 0 | 0 | 0 | ✅ |
| 需求上下文一致性 | 0 | 1 | 0 | ✅ |

## 阻塞问题汇总

{列出所有阻塞问题的编号、标题和所属模块}

## 跨模块一致性问题

{列出模块间不一致的发现，如功能清单有但需求详情没有的功能}

## 下一步

- 修复所有阻塞问题后，重新运行 prd-review 检查
- 建议同时关注建议问题，提升需求质量

Step 4: 输出总结

检查完成后，在对话中告知用户：

1. 检查了哪些模块
2. 各级问题数量
3. 是否可交付开发
4. 报告文件位置
5. 如有阻塞问题，列出前 3 个最关键的

知识库交叉校验做法

交叉校验是语义层面的对比，不是简单关键词匹配：

数据模型冲突： 从 PRD 提取实体名和字段名 → 在 data-model.md 中查找同名或语义相近实体 → 对比字段定义是否矛盾（如 PRD 中是 string，现有模型是 enum）→ 检查新外键是否与现有关系冲突

权限一致性： 从 PRD 提取角色名 → 在 user-roles.md 中查找 → 新角色标"建议"确认是否需新增 → 已有角色检查新权限是否与现有矩阵矛盾

流程衔接： 从 PRD 识别起始/结束节点 → 在 business-flows.md 中查找 → 检查输入是否是现有流程的输出 → 检查是否影响现有步骤

功能重复： 从 PRD 提取功能描述 → 在 existing-features.md 中搜索语义相似功能 → 高度相似标"建议"确认是增强还是新建

术语一致： 在 PRD 全文中识别业务术语 → 对照 glossary.md 的"业务定义"部分 → 同一概念用了不同名称标为"建议"

注意：知识库中的信息反映的是现有系统状态，PRD 中与现有系统不同不一定是"错误"——可能是有意的升级或改造。遇到不一致时，标为"建议"并说明差异，让作者确认是否有意为之，而不是直接标"阻塞"。

迭代使用

第一次运行 → 发现 3 个阻塞 + 5 个建议
    ↓
修改 PRD（修复 3 个阻塞）
    ↓
第二次运行 → 阻塞清零，新增 1 个建议
    ↓
修改 PRD（处理建议）
    ↓
第三次运行 → 全部通过，可以交付

每次运行报告完全覆盖上一次（非增量追加）。

与其他 skill 的关系

这个 skill 是 PRD 工作流的质量关卡环节：

project-import → knowledge-init → prd-draft → prd-review → [交付开发]
                                       ↑                |
                                       └── 修改后再检查 ←┘

• 前置：knowledge-init 生成的 prd-knowledge/ 提供交叉校验的依据
• 输入：PRD 文档（可由 prd-draft 或其他方式产出）
• 输出：检查报告（requirements/{模块名}/review/），指导 PRD 修改
• 约定：详见 conventions skill 中的目录规范

Common Pitfalls

把所有问题都标为阻塞： 一份 PRD 有 20 个阻塞，作者会崩溃。只标那些真正会导致开发停下来找 PM 确认的问题。

脱离知识库做判断： 知识库说现有系统用 RBAC，PRD 设计了 ABAC，这不一定是冲突——可能是有意升级。标"建议"并询问，而不是直接标"阻塞"。

忽略跨模块一致性： 功能清单写了"批量导出"但需求详情没有描述，业务流程有"审核"环节但权限管理没有"审核员"——这类问题往往最有价值。

review 报告自身包含代码细节： review 报告的读者和 PRD 的读者一样，包括产品和业务方。即使你通过 coding-knowledge 发现了技术层面的问题，也必须用产品语言描述。例如，写"PRD 未区分两种签章路径（传统签章和场景证书签章），建议在验收标准中分别覆盖"，而不是"genSealStrategyJson 和 genSealStrategyJsonForSceneCertificate 均需适配"。coding-knowledge 帮你发现问题，但问题描述和修改建议必须翻译为产品语言。