doc-prd-reviewer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesedoc-prd-reviewer
doc-prd-reviewer
Purpose
用途
Comprehensive content review and quality assurance for Product Requirements Documents (PRD). This skill performs deep content analysis beyond structural validation, checking link integrity, threshold consistency, BRD alignment, and identifying issues that require manual business review.
Layer: 2 (PRD Quality Assurance)
Upstream: PRD (from or )
doc-prd-autopilotdoc-prdDownstream: None (final QA gate before EARS generation)
为产品需求文档（PRD）提供全方位的内容审核与质量保障。本工具可执行超出结构校验的深度内容分析，检查链接完整性、阈值一致性、与BRD的对齐度，并识别需要人工业务审核的问题。
层级：2（PRD质量保障）
上游：PRD（来自或）
doc-prd-autopilotdoc-prd下游：无（生成EARS前的最终质量关）
When to Use This Skill
何时使用此工具
Use when:
doc-prd-reviewer- After PRD Generation: Run immediately after completes
doc-prd-autopilot - Manual PRD Edits: After making manual changes to a PRD
- Pre-EARS Check: Before running
doc-ears-autopilot - Periodic Review: Regular quality checks on existing PRDs
- CI/CD Integration: Automated review gate in documentation pipelines
Do NOT use when:
- PRD does not exist yet (use or
doc-prdfirst)doc-prd-autopilot - Need structural/schema validation only (use )
doc-prd-validator - Generating new PRD content (use )
doc-prd
当出现以下场景时使用：
doc-prd-reviewer- PRD生成后：在运行完成后立即执行
doc-prd-autopilot - 手动编辑PRD后：对PRD进行手动修改后
- EARS生成前检查：运行之前
doc-ears-autopilot - 定期审核：对存量PRD进行常规质量检查
- CI/CD集成：作为文档流水线中的自动化审核关口
禁止使用场景：
- PRD还未生成（请先使用或
doc-prd）doc-prd-autopilot - 仅需要结构/ schema校验（请使用）
doc-prd-validator - 生成新的PRD内容（请使用）
doc-prd
Skill vs Validator: Key Differences
本工具与校验器的核心差异
| Aspect | | |
|---|---|---|
| Focus | Schema compliance, EARS-Ready score | Content quality, cross-document consistency |
| Checks | Required sections, field formats | Link integrity, threshold alignment, placeholders |
| Auto-Fix | Structural issues only | Content issues (links, dates, placeholders) |
| Output | EARS-Ready score (numeric) | Review score + issue list |
| Phase | Phase 4 (Validation) | Phase 5 (Final Review) |
| Blocking | EARS-Ready < threshold blocks | Review score < threshold flags |
| 维度 | | |
|---|---|---|
| 核心关注点 | Schema合规性、EARS就绪评分 | 内容质量、跨文档一致性 |
| 检查项 | 必填章节、字段格式 | 链接完整性、阈值对齐性、占位符 |
| 自动修复 | 仅结构性问题 | 内容问题（链接、日期、占位符） |
| 输出 | EARS就绪评分（数值） | 审核评分 + 问题清单 |
| 阶段 | 第4阶段（校验） | 第5阶段（最终审核） |
| 阻断性 | EARS就绪评分低于阈值则阻断流程 | 审核评分低于阈值则标记风险 |
Review Workflow
审核工作流
mermaid
flowchart TD
A[Input: PRD Path] --> B[Load PRD Files]
B --> C{Sectioned or Monolithic?}
C -->|Sectioned| D[Load All Section Files]
C -->|Monolithic| E[Load Single File]
D --> F[Run Review Checks]
E --> F
subgraph Review["Review Checks"]
F --> G[1. Link Integrity]
G --> H[2. Threshold Consistency]
H --> I[3. BRD Alignment]
I --> J[4. Placeholder Detection]
J --> K[5. Traceability Tags]
K --> L[6. Section Completeness]
L --> M[7. Customer Content]
M --> M2[8. Naming Compliance]
M2 --> M3[9. Structure Compliance]
M3 --> M4[10. Upstream Drift Detection]
end
M4 --> N{Issues Found?}
N -->|Yes| O[Categorize Issues]
O --> P{Auto-Fixable?}
P -->|Yes| Q[Apply Auto-Fixes]
Q --> R[Re-run Affected Checks]
P -->|No| S[Flag for Manual Review]
R --> N
S --> T[Generate Report]
N -->|No| T
T --> U[Calculate Review Score]
U --> V{Score >= Threshold?}
V -->|Yes| W[PASS]
V -->|No| X[FAIL with Details]mermaid
flowchart TD
A[输入: PRD路径] --> B[加载PRD文件]
B --> C{是分章节版还是单文件版?}
C -->|分章节版| D[加载所有章节文件]
C -->|单文件版| E[加载单个文件]
D --> F[执行审核检查]
E --> F
subgraph 审核检查项["审核检查项"]
F --> G[1. 链接完整性]
G --> H[2. 阈值一致性]
H --> I[3. BRD对齐度]
I --> J[4. 占位符检测]
J --> K[5. 可追溯标签]
K --> L[6. 章节完整性]
L --> M[7. 客户端内容]
M --> M2[8. 命名合规性]
M2 --> M3[9. 结构合规性]
M3 --> M4[10. 上游文档漂移检测]
end
M4 --> N{发现问题?}
N -->|是| O[问题分类]
O --> P{可自动修复?}
P -->|是| Q[执行自动修复]
Q --> R[重新运行受影响的检查项]
P -->|否| S[标记为需人工审核]
R --> N
S --> T[生成报告]
N -->|否| T
T --> U[计算审核评分]
U --> V{评分 >= 阈值?}
V -->|是| W[通过]
V -->|否| X[不通过，附详细说明]Review Checks
审核检查项
1. Link Integrity
1. 链接完整性
Validates all internal document links resolve correctly.
Scope:
- Navigation links (,
[Previous: ...])[Next: ...] - Section cross-references ()
[See Section 8.2](...) - Index to section links
- External documentation links (warns if unreachable)
Detection:
Scanning PRD-01 for internal links...
├── PRD-01.0_index.md: 17 links found
│ ├── PRD-01.1_document_control.md ✓
│ ├── PRD-01.2_executive_summary.md ✓
│ ├── PRD-01.18_missing_section.md ✗ NOT FOUND
│ └── ...
└── Result: 1 broken link foundAuto-Fix:
- Remove broken links to non-existent sections
- Correct path typos if target exists with similar name
- Update relative paths if file was moved
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-L001 | Error | Broken internal link |
| REV-L002 | Warning | External link unreachable |
| REV-L003 | Info | Link path uses absolute instead of relative |
校验所有内部文档链接可正常跳转。
检查范围:
- 导航链接（、
[上一篇: ...]）[下一篇: ...] - 章节交叉引用（）
[参见第8.2节](...) - 索引指向章节的链接
- 外部文档链接（不可达时给出警告）
检测示例:
Scanning PRD-01 for internal links...
├── PRD-01.0_index.md: 17 links found
│ ├── PRD-01.1_document_control.md ✓
│ ├── PRD-01.2_executive_summary.md ✓
│ ├── PRD-01.18_missing_section.md ✗ NOT FOUND
│ └── ...
└── Result: 1 broken link found自动修复:
- 移除指向不存在章节的无效链接
- 如果存在名称相似的目标文件，修正路径拼写错误
- 如果文件被移动，更新相对路径
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-L001 | 错误 | 内部链接损坏 |
| REV-L002 | 警告 | 外部链接不可达 |
| REV-L003 | 提示 | 链接使用绝对路径而非相对路径 |
2. Threshold Consistency
2. 阈值一致性
Verifies performance metrics match across all sections.
Scope:
- Section 5 (Success Metrics) thresholds
- Section 9 (Quality Attributes) performance targets
- Section 17/20 (Appendix B.1) timing profile matrix
- Cross-references to BRD thresholds
Detection:
Comparing thresholds across sections...
├── Operation: auth.p99
│ ├── Section 5 (Success Metrics): 100ms ✓
│ ├── Section 9 (Quality Attributes): 100ms ✓
│ ├── Section 17 (Timing Matrix): 100ms ✓
│ └── BRD-01 (Source): 100ms ✓
├── Operation: authz.p99
│ ├── Section 5: 10ms ✓
│ ├── Section 9: 15ms ✗ MISMATCH
│ ├── Section 17: 10ms ✓
│ └── BRD-01: 10ms ✓
└── Result: 1 inconsistency foundAuto-Fix:
- Align PRD values to BRD source (authoritative)
- Update all sections to use consistent value
- Add comment noting auto-fix with timestamp
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-T001 | Error | Threshold mismatch across PRD sections |
| REV-T002 | Error | Threshold differs from BRD source |
| REV-T003 | Warning | Threshold unit inconsistency (ms vs s) |
| REV-T004 | Info | Threshold stricter than BRD (acceptable) |
验证所有章节的性能指标保持一致。
检查范围:
- 第5节（成功指标）的阈值
- 第9节（质量属性）的性能目标
- 第17/20节（附录B.1）的时序配置矩阵
- 对BRD阈值的交叉引用
检测示例:
Comparing thresholds across sections...
├── Operation: auth.p99
│ ├── Section 5 (Success Metrics): 100ms ✓
│ ├── Section 9 (Quality Attributes): 100ms ✓
│ ├── Section 17 (Timing Matrix): 100ms ✓
│ └── BRD-01 (Source): 100ms ✓
├── Operation: authz.p99
│ ├── Section 5: 10ms ✓
│ ├── Section 9: 15ms ✗ MISMATCH
│ ├── Section 17: 10ms ✓
│ └── BRD-01: 10ms ✓
└── Result: 1 inconsistency found自动修复:
- 将PRD中的值与权威的BRD源对齐
- 更新所有章节使用统一的数值
- 添加注释标注自动修复操作与时间戳
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-T001 | 错误 | PRD各章节阈值不一致 |
| REV-T002 | 错误 | 阈值与BRD源不一致 |
| REV-T003 | 警告 | 阈值单位不一致（ms与s混用） |
| REV-T004 | 提示 | 阈值比BRD要求更严格（可接受） |
3. BRD Alignment
3. BRD对齐度
Validates PRD requirements accurately reflect BRD source.
Scope:
- Every PRD requirement maps to a BRD requirement
- No orphaned requirements (PRD without BRD source)
- No missing requirements (BRD without PRD mapping)
- Scope boundaries match
Detection:
Verifying PRD requirements map to BRD source...
├── PRD.01.01.01 → BRD.01.01.01 (Multi-Provider Auth) ✓
├── PRD.01.01.02 → BRD.01.01.02 (4D Authorization) ✓
├── PRD.01.01.03 → BRD.01.01.03 (Trust Levels) ✓
├── PRD.01.01.09 → ??? ✗ NO BRD MAPPING
├── BRD.01.01.10 → ??? ✗ NO PRD MAPPING (deferred)
└── Result: 11/12 aligned, 1 orphan, 1 missing
Scope Alignment:
├── PRD In-Scope vs BRD In-Scope: MATCH ✓
├── PRD Out-Scope vs BRD Out-Scope: MATCH ✓
└── Deferred items: 2 (correctly marked)Manual Review Required:
- Orphaned requirements need justification
- Missing requirements need explicit deferral note
- Scope mismatches need business decision
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-A001 | Error | PRD requirement without BRD source |
| REV-A002 | Warning | BRD requirement without PRD mapping |
| REV-A003 | Error | Scope mismatch (PRD vs BRD) |
| REV-A004 | Info | Requirement correctly marked as deferred |
校验PRD需求准确反映BRD源内容。
检查范围:
- 每个PRD需求都对应一个BRD需求
- 无孤立需求（PRD需求无对应BRD源）
- 无缺失需求（BRD需求未映射到PRD）
- 范围边界保持一致
检测示例:
Verifying PRD requirements map to BRD source...
├── PRD.01.01.01 → BRD.01.01.01 (Multi-Provider Auth) ✓
├── PRD.01.01.02 → BRD.01.01.02 (4D Authorization) ✓
├── PRD.01.01.03 → BRD.01.01.03 (Trust Levels) ✓
├── PRD.01.01.09 → ??? ✗ NO BRD MAPPING
├── BRD.01.01.10 → ??? ✗ NO PRD MAPPING (deferred)
└── Result: 11/12 aligned, 1 orphan, 1 missing
Scope Alignment:
├── PRD In-Scope vs BRD In-Scope: MATCH ✓
├── PRD Out-Scope vs BRD Out-Scope: MATCH ✓
└── Deferred items: 2 (correctly marked)需要人工审核:
- 孤立需求需要提供合理性说明
- 缺失需求需要明确标注延期说明
- 范围不匹配需要业务方决策
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-A001 | 错误 | PRD需求无对应BRD源 |
| REV-A002 | 警告 | BRD需求未映射到PRD |
| REV-A003 | 错误 | 范围不匹配（PRD与BRD不一致） |
| REV-A004 | 提示 | 需求已正确标记为延期 |
4. Placeholder Detection
4. 占位符检测
Identifies incomplete content requiring replacement.
Scope:
- ,
[TODO],[TBD]text[PLACEHOLDER] - Template dates: ,
YYYY-MM-DDTHH:MM:SSMM/DD/YYYY - Template names: ,
[Name],[Author][Reviewer] - Empty sections:
<!-- Content here --> - Lorem ipsum or sample text
Detection:
Scanning for placeholder text...
├── [TODO]: 0 found ✓
├── [TBD]: 1 found
│ └── PRD-01.10_customer_content.md:42: "[TBD: Marketing copy]"
├── YYYY-MM-DDTHH:MM:SS: 0 found ✓
├── [Name]: 0 found ✓
├── Empty sections: 0 found ✓
└── Result: 1 placeholder foundAuto-Fix:
- Replace with current datetime
YYYY-MM-DDTHH:MM:SS - Replace with document author from metadata
[Name] - Remove empty comment placeholders
- Flag /
[TODO]for manual completion[TBD]
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-P001 | Error | [TODO] placeholder found |
| REV-P002 | Error | [TBD] placeholder found |
| REV-P003 | Warning | Template date not replaced |
| REV-P004 | Warning | Template name not replaced |
| REV-P005 | Warning | Empty section content |
识别需要替换的不完整内容。
检查范围:
- 、
[TODO]、[TBD]文本[PLACEHOLDER] - 模板日期：、
YYYY-MM-DDTHH:MM:SSMM/DD/YYYY - 模板名称：、
[Name]、[Author][Reviewer] - 空章节：
<!-- Content here --> - Lorem ipsum或示例文本
检测示例:
Scanning for placeholder text...
├── [TODO]: 0 found ✓
├── [TBD]: 1 found
│ └── PRD-01.10_customer_content.md:42: "[TBD: Marketing copy]"
├── YYYY-MM-DDTHH:MM:SS: 0 found ✓
├── [Name]: 0 found ✓
├── Empty sections: 0 found ✓
└── Result: 1 placeholder found自动修复:
- 将替换为当前日期时间
YYYY-MM-DDTHH:MM:SS - 将替换为元数据中的文档作者
[Name] - 移除空的注释占位符
- 标记/
[TODO]待人工补全[TBD]
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-P001 | 错误 | 发现[TODO]占位符 |
| REV-P002 | 错误 | 发现[TBD]占位符 |
| REV-P003 | 警告 | 模板日期未替换 |
| REV-P004 | 警告 | 模板名称未替换 |
| REV-P005 | 警告 | 章节内容为空 |
5. Traceability Tags
5. 可追溯标签
Validates , , and tags.
@brd:@depends:@discoverability:Scope:
- All tags reference valid BRD IDs
@brd: BRD.XX.XX.XX - references exist
@depends: PRD-XX - references exist
@discoverability: PRD-XX - Tag format follows convention
Detection:
Validating traceability tags...
├── @brd tags: 15 found
│ ├── BRD.01.01.01 ✓ (exists in BRD-01)
│ ├── BRD.01.01.02 ✓
│ ├── BRD.01.99.01 ✗ NOT FOUND in BRD
│ └── ...
├── @depends tags: 2 found
│ ├── PRD-06 ✓ (exists)
│ └── PRD-07 ✓ (exists)
├── @discoverability tags: 2 found
│ ├── PRD-02 ✗ (planned, not yet created)
│ └── PRD-03 ✗ (planned, not yet created)
└── Result: 1 invalid @brd, 2 forward references (acceptable)Auto-Fix:
- Remove invalid tags
@brd - Correct typos in tag IDs if close match exists
- Add suffix to forward references
(planned)
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-TR001 | Error | @brd tag references non-existent BRD ID |
| REV-TR002 | Warning | @depends references non-existent PRD |
| REV-TR003 | Info | @discoverability is forward reference |
| REV-TR004 | Warning | Tag format malformed |
校验、和标签有效性。
@brd:@depends:@discoverability:检查范围:
- 所有标签引用的BRD ID有效
@brd: BRD.XX.XX.XX - 引用的PRD存在
@depends: PRD-XX - 引用的PRD存在
@discoverability: PRD-XX - 标签格式符合规范
检测示例:
Validating traceability tags...
├── @brd tags: 15 found
│ ├── BRD.01.01.01 ✓ (exists in BRD-01)
│ ├── BRD.01.01.02 ✓
│ ├── BRD.01.99.01 ✗ NOT FOUND in BRD
│ └── ...
├── @depends tags: 2 found
│ ├── PRD-06 ✓ (exists)
│ └── PRD-07 ✓ (exists)
├── @discoverability tags: 2 found
│ ├── PRD-02 ✗ (planned, not yet created)
│ └── PRD-03 ✗ (planned, not yet created)
└── Result: 1 invalid @brd, 2 forward references (acceptable)自动修复:
- 移除无效的标签
@brd - 如果存在近似匹配，修正标签ID的拼写错误
- 为前向引用添加后缀
(planned)
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-TR001 | 错误 | @brd标签引用不存在的BRD ID |
| REV-TR002 | 警告 | @depends引用不存在的PRD |
| REV-TR003 | 提示 | @discoverability为前向引用 |
| REV-TR004 | 警告 | 标签格式错误 |
6. Section Completeness
6. 章节完整性
Verifies all required sections have substantive content.
Scope:
- Minimum word count per section (configurable)
- Section headers present
- Tables have data rows (not just headers)
- Mermaid diagrams render properly
Detection:
Checking section completeness...
├── Section 1 (Document Control): 150 words ✓
├── Section 2 (Executive Summary): 280 words ✓
├── Section 10 (Customer Content): 45 words ⚠ THIN
├── Section 17 (Appendices): 820 words ✓
├── Table check: 12 tables, all have data rows ✓
├── Mermaid check: 3 diagrams, all valid ✓
└── Result: 16/17 complete, 1 thin sectionMinimum Word Counts (configurable):
| Section | Minimum Words |
|---|---|
| Executive Summary | 100 |
| Problem Statement | 75 |
| Functional Requirements | 200 |
| Quality Attributes | 100 |
| Customer Content | 100 |
| Risk Assessment | 75 |
| Appendices | 200 |
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-S001 | Error | Required section missing entirely |
| REV-S002 | Warning | Section below minimum word count |
| REV-S003 | Warning | Table has no data rows |
| REV-S004 | Error | Mermaid diagram syntax error |
验证所有必填章节都有实质内容。
检查范围:
- 每个章节的最低字数（可配置）
- 章节标题存在
- 表格有数据行（不只有表头）
- Mermaid图可正常渲染
检测示例:
Checking section completeness...
├── Section 1 (Document Control): 150 words ✓
├── Section 2 (Executive Summary): 280 words ✓
├── Section 10 (Customer Content): 45 words ⚠ THIN
├── Section 17 (Appendices): 820 words ✓
├── Table check: 12 tables, all have data rows ✓
├── Mermaid check: 3 diagrams, all valid ✓
└── Result: 16/17 complete, 1 thin section最低字数要求（可配置）:
| 章节 | 最低字数 |
|---|---|
| 执行摘要 | 100 |
| 问题陈述 | 75 |
| 功能需求 | 200 |
| 质量属性 | 100 |
| 客户端内容 | 100 |
| 风险评估 | 75 |
| 附录 | 200 |
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-S001 | 错误 | 必填章节完全缺失 |
| REV-S002 | 警告 | 章节字数低于最低要求 |
| REV-S003 | 警告 | 表格无数据行 |
| REV-S004 | 错误 | Mermaid图语法错误 |
7. Customer Content Review
7. 客户端内容审核
Flags Section 10 for mandatory business/marketing review.
Scope:
- Section 10 (Customer-Facing Content) exists
- Content is substantive (not placeholder)
- Marketing language appropriate
- No technical jargon in customer-facing text
Detection:
Reviewing customer-facing content (Section 10)...
├── Section exists: ✓
├── Word count: 180 words ✓
├── Placeholder check: PASS ✓
├── Technical jargon scan:
│ ├── "4D Matrix" - technical term found
│ ├── "OIDC" - acronym may need explanation
│ └── "mTLS" - technical term found
└── Result: FLAG for marketing review (3 technical terms)Manual Review Required:
- All Section 10 content requires business sign-off
- Technical terms need customer-friendly alternatives
- Messaging alignment with brand guidelines
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-C001 | Error | Section 10 missing |
| REV-C002 | Warning | Section 10 is placeholder content |
| REV-C003 | Info | Technical jargon in customer content |
| REV-C004 | Flag | Requires marketing/business review |
标记第10节为强制业务/营销审核项。
检查范围:
- 第10节（面向客户端的内容）存在
- 内容为实质内容（非占位符）
- 营销用语合适
- 面向客户端的文本无技术术语
检测示例:
Reviewing customer-facing content (Section 10)...
├── Section exists: ✓
├── Word count: 180 words ✓
├── Placeholder check: PASS ✓
├── Technical jargon scan:
│ ├── "4D Matrix" - technical term found
│ ├── "OIDC" - acronym may need explanation
│ └── "mTLS" - technical term found
└── Result: FLAG for marketing review (3 technical terms)需要人工审核:
- 所有第10节内容需要业务方签字确认
- 技术术语需要替换为客户友好的表述
- 消息传递与品牌指南对齐
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-C001 | 错误 | 第10节缺失 |
| REV-C002 | 警告 | 第10节为占位符内容 |
| REV-C003 | 提示 | 客户端内容中存在技术术语 |
| REV-C004 | 标记 | 需要营销/业务审核 |
8. Naming Compliance
8. 命名合规性
Validates element IDs and threshold tags follow standards.
doc-namingScope:
- Element IDs use format
PRD.NN.TT.SS - Element type codes valid for PRD (01-09, 11, 22, 24)
- Threshold tags use format
@threshold: PRD.NN.key - No legacy patterns (US-NNN, FR-NNN, AC-NNN, F-NNN)
Detection:
Validating naming compliance (per doc-naming skill)...
├── Element IDs: 24 found
│ ├── PRD.01.01.01 ✓ (valid format, code 01 valid for PRD)
│ ├── PRD.01.09.05 ✓ (valid format, code 09 valid for PRD)
│ ├── PRD.01.25.01 ✗ (code 25 not valid for PRD - EARS only)
│ └── ...
├── Threshold tags: 8 found
│ ├── @threshold: PRD.01.perf.auth.p99 ✓
│ ├── @threshold: perf.auth.p99 ✗ (missing PRD.NN prefix)
│ └── ...
├── Legacy patterns: 2 found
│ ├── US-001 ✗ (deprecated - use PRD.NN.09.SS)
│ └── FR-003 ✗ (deprecated - use PRD.NN.01.SS)
└── Result: 3 naming violationsAuto-Fix:
- Convert legacy patterns to unified format
- Add missing prefix to threshold tags
PRD.NN - Suggest correct element type codes
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-N001 | Error | Invalid element ID format |
| REV-N002 | Error | Element type code not valid for PRD |
| REV-N003 | Error | Legacy pattern detected (US-NNN, FR-NNN, etc.) |
| REV-N004 | Error | Threshold tag missing document reference |
| REV-N005 | Warning | Threshold key format non-standard |
Reference: See skill for complete naming rules.
doc-naming校验元素ID和阈值标签符合标准。
doc-naming检查范围:
- 元素ID使用格式
PRD.NN.TT.SS - 元素类型代码对PRD有效（01-09、11、22、24）
- 阈值标签使用格式
@threshold: PRD.NN.key - 无旧版命名模式（US-NNN、FR-NNN、AC-NNN、F-NNN）
检测示例:
Validating naming compliance (per doc-naming skill)...
├── Element IDs: 24 found
│ ├── PRD.01.01.01 ✓ (valid format, code 01 valid for PRD)
│ ├── PRD.01.09.05 ✓ (valid format, code 09 valid for PRD)
│ ├── PRD.01.25.01 ✗ (code 25 not valid for PRD - EARS only)
│ └── ...
├── Threshold tags: 8 found
│ ├── @threshold: PRD.01.perf.auth.p99 ✓
│ ├── @threshold: perf.auth.p99 ✗ (missing PRD.NN prefix)
│ └── ...
├── Legacy patterns: 2 found
│ ├── US-001 ✗ (deprecated - use PRD.NN.09.SS)
│ └── FR-003 ✗ (deprecated - use PRD.NN.01.SS)
└── Result: 3 naming violations自动修复:
- 将旧版命名模式转换为统一格式
- 为阈值标签添加缺失的前缀
PRD.NN - 推荐正确的元素类型代码
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-N001 | 错误 | 元素ID格式无效 |
| REV-N002 | 错误 | 元素类型代码对PRD无效 |
| REV-N003 | 错误 | 检测到旧版命名模式（US-NNN、FR-NNN等） |
| REV-N004 | 错误 | 阈值标签缺失文档引用 |
| REV-N005 | 警告 | 阈值键格式不符合标准 |
参考：完整命名规则请参见工具文档。
doc-naming9. Structure Compliance (CRITICAL)
9. 结构合规性（关键）
Validates PRD follows the mandatory nested folder rule.
Nested Folder Rule: ALL PRDs MUST be in nested folders regardless of size.
Required Structure:
| PRD Type | Required Location |
|---|---|
| Monolithic | |
| Sectioned | |
Detection:
Validating folder structure...
├── PRD Location: docs/02_PRD/PRD-01_f1_iam/PRD-01_f1_iam.md
├── Expected Folder: PRD-01_f1_iam ✓
├── Parent Path: docs/02_PRD/ ✓
├── Nested Structure: Valid ✓
└── Result: PASSFailure Detection:
Validating folder structure...
├── PRD Location: docs/02_PRD/PRD-02_f2_session.md
├── Expected: docs/02_PRD/PRD-02_f2_session/PRD-02_f2_session.md
├── Nested Structure: INVALID ✗
└── Result: FAIL - PRD not in nested folderAuto-Fix:
- Create the nested folder
docs/02_PRD/PRD-NN_{slug}/ - Move the PRD file(s) into the folder
- Update all internal links (navigation, cross-references)
- Update upstream BRD links: →
../01_BRD/../../01_BRD/ - Update any glossary links to correct path
Error Codes:
| Code | Severity | Description |
|---|---|---|
| REV-STR001 | Error | PRD not in nested folder (blocking) |
| REV-STR002 | Error | PRD folder name doesn't match PRD ID |
| REV-STR003 | Warning | Monolithic PRD should be sectioned (>25KB) |
| REV-STR004 | Error | BRD link path incorrect for nested folder |
This check is BLOCKING - PRD must pass structure validation before other checks proceed.
校验PRD符合强制嵌套文件夹规则。
嵌套文件夹规则：所有PRD无论大小都必须存放在嵌套文件夹中。
要求结构:
| PRD类型 | 要求存放路径 |
|---|---|
| 单文件版 | |
| 分章节版 | |
检测示例:
Validating folder structure...
├── PRD Location: docs/02_PRD/PRD-01_f1_iam/PRD-01_f1_iam.md
├── Expected Folder: PRD-01_f1_iam ✓
├── Parent Path: docs/02_PRD/ ✓
├── Nested Structure: Valid ✓
└── Result: PASS失败检测示例:
Validating folder structure...
├── PRD Location: docs/02_PRD/PRD-02_f2_session.md
├── Expected: docs/02_PRD/PRD-02_f2_session/PRD-02_f2_session.md
├── Nested Structure: INVALID ✗
└── Result: FAIL - PRD not in nested folder自动修复:
- 创建嵌套文件夹
docs/02_PRD/PRD-NN_{slug}/ - 将PRD文件移动到该文件夹中
- 更新所有内部链接（导航、交叉引用）
- 更新上游BRD链接：→
../01_BRD/../../01_BRD/ - 更新所有术语表链接为正确路径
错误码:
| 错误码 | 严重级别 | 描述 |
|---|---|---|
| REV-STR001 | 错误 | PRD未存放在嵌套文件夹中（阻断性） |
| REV-STR002 | 错误 | PRD文件夹名称与PRD ID不匹配 |
| REV-STR003 | 警告 | 单文件PRD体积超过25KB，建议拆分为分章节版 |
| REV-STR004 | 错误 | 嵌套文件夹中的BRD链接路径不正确 |
此检查为阻断性检查——PRD必须先通过结构校验，才能继续执行其他检查。
10. Upstream Drift Detection (Mandatory Cache)
10. 上游文档漂移检测（强制缓存）
Detects when upstream source documents have been modified after the PRD was created or last updated. The drift cache is mandatory - the reviewer MUST create/update it after every review.
Purpose: Identifies stale PRD content that may not reflect current BRD documentation. When upstream documents (BRD specifications, business requirements) change, the PRD may need updates to maintain alignment.
Scope:
- tag targets (BRD documents, technical specifications)
@ref: - tag references
@brd: - Traceability section upstream artifact links
- Any markdown links to or source documents
../01_BRD/
检测上游源文档在PRD创建或上次更新后是否被修改。漂移缓存为强制要求——审核工具每次审核后必须创建/更新缓存。
用途：识别可能未与当前BRD文档对齐的过时PRD内容。当上游文档（BRD规范、业务需求）变更时，PRD可能需要更新以保持对齐。
检查范围:
- 标签目标（BRD文档、技术规范）
@ref: - 标签引用
@brd: - 可追溯章节的上游工件链接
- 所有指向或源文档的markdown链接
../01_BRD/
10.1 Drift Cache File (MANDATORY)
10.1 漂移缓存文件（强制要求）
Location:
docs/02_PRD/{PRD_folder}/.drift_cache.jsonIMPORTANT: The reviewer MUST:
- Read the cache if it exists (for hash comparison)
- Create the cache if it doesn't exist
- Update the cache after every review with current hashes
Cache Schema:
json
{
"schema_version": "1.0",
"document_id": "PRD-01",
"document_version": "1.0",
"last_reviewed": "2026-02-10T17:00:00",
"reviewer_version": "1.4",
"upstream_documents": {
"../../01_BRD/BRD-01_f1_iam/BRD-01.0_index.md": {
"hash": "sha256:a1b2c3d4e5f6g7h8i9j0...",
"last_modified": "2026-02-10T15:34:26",
"file_size": 50781,
"version": "1.0",
"sections_tracked": ["#7-functional-requirements", "#8-non-functional-requirements"]
},
"../../01_BRD/BRD-01_f1_iam/BRD-01.7_functional_requirements.md": {
"hash": "sha256:k1l2m3n4o5p6q7r8s9t0...",
"last_modified": "2026-02-10T15:34:21",
"file_size": 4730,
"version": "1.0",
"sections_tracked": ["#authentication", "#authorization"]
}
},
"review_history": [
{
"date": "2026-02-10T16:30:00",
"score": 97,
"drift_detected": false,
"report_version": "v002"
}
]
}存放路径：
docs/02_PRD/{PRD_folder}/.drift_cache.json重要说明：审核工具必须：
- 如果缓存存在则读取缓存（用于哈希对比）
- 如果缓存不存在则创建缓存
- 每次审核后使用当前哈希更新缓存
缓存Schema:
json
{
"schema_version": "1.0",
"document_id": "PRD-01",
"document_version": "1.0",
"last_reviewed": "2026-02-10T17:00:00",
"reviewer_version": "1.4",
"upstream_documents": {
"../../01_BRD/BRD-01_f1_iam/BRD-01.0_index.md": {
"hash": "sha256:a1b2c3d4e5f6g7h8i9j0...",
"last_modified": "2026-02-10T15:34:26",
"file_size": 50781,
"version": "1.0",
"sections_tracked": ["#7-functional-requirements", "#8-non-functional-requirements"]
},
"../../01_BRD/BRD-01_f1_iam/BRD-01.7_functional_requirements.md": {
"hash": "sha256:k1l2m3n4o5p6q7r8s9t0...",
"last_modified": "2026-02-10T15:34:21",
"file_size": 4730,
"version": "1.0",
"sections_tracked": ["#authentication", "#authorization"]
}
},
"review_history": [
{
"date": "2026-02-10T16:30:00",
"score": 97,
"drift_detected": false,
"report_version": "v002"
}
]
}10.2 Detection Algorithm (Three-Phase)
10.2 检测算法（三阶段）
PHASE 1: Load Cache (if exists)
=========================================
1. Check for .drift_cache.json in PRD folder
2. If exists:
- Load cached hashes and metadata
- Set detection_mode = "hash_comparison"
3. If not exists:
- Set detection_mode = "timestamp_only"
- Will create cache at end of review
PHASE 2: Detect Drift
=========================================
For each upstream reference in PRD:
A. Extract reference:
- @ref: tags → [path, section anchor]
- @brd: tags → [BRD ID, requirement ID]
- Links to ../01_BRD/ → [path]
- Traceability table upstream artifacts → [path]
B. Resolve and validate:
- Resolve path to absolute file path
- Check file exists (skip if covered by Check #1)
- Get file stats: mtime, size
C. Compare (based on detection_mode):
IF detection_mode == "hash_comparison":
- Compute SHA-256 hash of current file content
- Compare to cached hash
- IF hash differs:
- Calculate change_percentage
- Flag as CONTENT_DRIFT (REV-D002)
- IF change > 20%: Flag as CRITICAL (REV-D005)
ELSE (timestamp_only):
- Compare file mtime > PRD last_updated
- IF mtime > PRD date:
- Flag as TIMESTAMP_DRIFT (REV-D001)
D. Check version field (if YAML frontmatter):
- Extract version from upstream doc
- Compare to cached version
- IF version incremented: Flag REV-D003
PHASE 3: Update Cache (MANDATORY)
=========================================
1. Compute SHA-256 hash for ALL upstream documents
2. Create/update .drift_cache.json with:
- Current hashes
- Current timestamps
- Current file sizes
- Review metadata
3. Append to review_history array阶段1: 加载缓存（如果存在）
=========================================
1. 检查PRD文件夹中是否存在.drift_cache.json
2. 如果存在:
- 加载缓存的哈希和元数据
- 设置检测模式 = "hash_comparison"
3. 如果不存在:
- 设置检测模式 = "timestamp_only"
- 审核结束后会创建缓存
阶段2: 检测漂移
=========================================
遍历PRD中的每个上游引用:
A. 提取引用:
- @ref: 标签 → [路径, 章节锚点]
- @brd: 标签 → [BRD ID, 需求ID]
- 指向../01_BRD/的链接 → [路径]
- 可追溯表中的上游工件 → [路径]
B. 解析与校验:
- 将路径解析为绝对文件路径
- 检查文件是否存在（如果已通过检查项1校验则跳过）
- 获取文件属性：修改时间、大小
C. 对比（基于检测模式）:
如果检测模式 == "hash_comparison":
- 计算当前文件内容的SHA-256哈希
- 与缓存的哈希对比
- 如果哈希不同:
- 计算变更百分比
- 标记为CONTENT_DRIFT（REV-D002）
- 如果变更 > 20%: 标记为严重（REV-D005）
否则（timestamp_only模式）:
- 对比文件修改时间 > PRD上次更新时间
- 如果修改时间晚于PRD日期:
- 标记为TIMESTAMP_DRIFT（REV-D001）
D. 检查版本字段（如果有YAML frontmatter）:
- 从上游文档提取版本
- 与缓存的版本对比
- 如果版本升级: 标记REV-D003
阶段3: 更新缓存（强制要求）
=========================================
1. 为所有上游文档计算SHA-256哈希
2. 创建/更新.drift_cache.json，包含:
- 当前哈希
- 当前时间戳
- 当前文件大小
- 审核元数据
3. 追加到review_history数组10.3 Hash Calculation
10.3 哈希计算
python
import hashlib
from pathlib import Path
def compute_file_hash(file_path: str) -> str:
"""Compute SHA-256 hash of file content."""
sha256 = hashlib.sha256()
with open(file_path, 'rb') as f:
for chunk in iter(lambda: f.read(8192), b''):
sha256.update(chunk)
return f"sha256:{sha256.hexdigest()}"
def compute_section_hash(file_path: str, section_anchor: str) -> str:
"""Compute hash of specific section (for anchor references)."""
content = Path(file_path).read_text()
# Extract section from anchor to next heading
section_pattern = f"#{section_anchor.lstrip('#')}"
# ... section extraction logic ...
section_content = extract_section(content, section_pattern)
return f"sha256:{hashlib.sha256(section_content.encode()).hexdigest()}"
def calculate_change_percentage(old_hash: str, new_content: str) -> float:
"""Estimate change percentage using content diff."""
# Use difflib to calculate similarity ratio
import difflib
# ... comparison logic ...
return change_percentagepython
import hashlib
from pathlib import Path
def compute_file_hash(file_path: str) -> str:
"""Compute SHA-256 hash of file content."""
sha256 = hashlib.sha256()
with open(file_path, 'rb') as f:
for chunk in iter(lambda: f.read(8192), b''):
sha256.update(chunk)
return f"sha256:{sha256.hexdigest()}"
def compute_section_hash(file_path: str, section_anchor: str) -> str:
"""Compute hash of specific section (for anchor references)."""
content = Path(file_path).read_text()
# Extract section from anchor to next heading
section_pattern = f"#{section_anchor.lstrip('#')}"
# ... section extraction logic ...
section_content = extract_section(content, section_pattern)
return f"sha256:{hashlib.sha256(section_content.encode()).hexdigest()}"
def calculate_change_percentage(old_hash: str, new_content: str) -> float:
"""Estimate change percentage using content diff."""
# Use difflib to calculate similarity ratio
import difflib
# ... comparison logic ...
return change_percentage10.4 Error Codes
10.4 错误码
| Code | Severity | Description | Trigger |
|---|---|---|---|
| REV-D001 | Warning | Upstream document modified after PRD creation | mtime > PRD date (no cache) |
| REV-D002 | Warning | Referenced content has changed | hash mismatch (with cache) |
| REV-D003 | Info | Upstream document version incremented | version field changed |
| REV-D004 | Info | New content added to upstream | file size increased >10% |
| REV-D005 | Error | Critical modification (>20% change) | hash diff >20% |
| REV-D006 | Info | Cache created (first review) | no prior cache existed |
| 错误码 | 严重级别 | 描述 | 触发条件 |
|---|---|---|---|
| REV-D001 | 警告 | 上游文档在PRD创建后被修改 | 修改时间晚于PRD日期（无缓存） |
| REV-D002 | 警告 | 引用内容已变更 | 哈希不匹配（有缓存） |
| REV-D003 | 提示 | 上游文档版本升级 | 版本字段变更 |
| REV-D004 | 提示 | 上游文档新增内容 | 文件大小增加超过10% |
| REV-D005 | 错误 | 严重变更（变更>20%） | 哈希差异超过20% |
| REV-D006 | 提示 | 缓存已创建（首次审核） | 之前无缓存 |
10.5 Report Output
10.5 报告输出
markdown
undefinedmarkdown
undefined9. Upstream Drift Detection (5/5)
9. 上游漂移检测（5/5）
Cache Status
缓存状态
| Field | Value |
|---|---|
| Cache File | |
| Cache Status | ✅ Updated |
| Detection Mode | Hash Comparison |
| Documents Tracked | 2 |
| 字段 | 值 |
|---|---|
| 缓存文件 | |
| 缓存状态 | ✅ 已更新 |
| 检测模式 | 哈希对比 |
| 跟踪文档数 | 2 |
Upstream Document Analysis
上游文档分析
| Upstream Document | Hash Status | Last Modified | Change % | Status |
|---|---|---|---|---|
| BRD-01.0_index.md | ✅ Match | 2026-02-10T15:34:26 | 0% | Current |
| BRD-01.7_functional_requirements.md | ✅ Match | 2026-02-10T15:34:21 | 0% | Current |
| 上游文档 | 哈希状态 | 上次修改时间 | 变更百分比 | 状态 |
|---|---|---|---|---|
| BRD-01.0_index.md | ✅ 匹配 | 2026-02-10T15:34:26 | 0% | 已同步 |
| BRD-01.7_functional_requirements.md | ✅ 匹配 | 2026-02-10T15:34:21 | 0% | 已同步 |
Drift Summary
漂移汇总
| Status | Count | Details |
|---|---|---|
| ✅ Current | 2 | All upstream documents synchronized |
| ⚠️ Warning | 0 | No drift detected |
| ❌ Critical | 0 | No major changes |
Cache updated: 2026-02-10T17:00:00
---| 状态 | 数量 | 详情 |
|---|---|---|
| ✅ 已同步 | 2 | 所有上游文档已同步 |
| ⚠️ 警告 | 0 | 未检测到漂移 |
| ❌ 严重 | 0 | 无重大变更 |
缓存更新时间: 2026-02-10T17:00:00
---10.6 Configuration
10.6 配置
| Setting | Default | Description |
|---|---|---|
| true | Mandatory - always create/update cache |
| 7 | Days before timestamp drift becomes Warning |
| 20 | Percentage change for critical drift |
| true | Track individual section hashes for anchored refs |
| 10 | Maximum review_history entries to retain |
| 设置 | 默认值 | 描述 |
|---|---|---|
| true | 强制要求 - 始终创建/更新缓存 |
| 7 | 时间戳漂移触发警告的天数阈值 |
| 20 | 严重漂移的变更百分比阈值 |
| true | 为锚点引用跟踪单个章节的哈希 |
| 10 | 保留的最大review_history条目数 |
Review Score Calculation
审核评分计算
Scoring Formula:
| Category | Weight | Calculation |
|---|---|---|
| Link Integrity | 10% | (valid_links / total_links) × 10 |
| Threshold Consistency | 10% | (consistent_thresholds / total_thresholds) × 10 |
| BRD Alignment | 18% | (aligned_requirements / total_requirements) × 18 |
| Placeholder Detection | 10% | (no_placeholders ? 10 : 10 - (placeholder_count × 2)) |
| Traceability Tags | 10% | (valid_tags / total_tags) × 10 |
| Section Completeness | 10% | (complete_sections / total_sections) × 10 |
| Customer Content | 5% | (exists && substantive ? 5 : 0) |
| Naming Compliance | 10% | (valid_ids / total_ids) × 10 |
| Structure Compliance | 12% | (nested_folder_valid ? 12 : 0) - BLOCKING |
| Upstream Drift | 5% | (fresh_refs / total_refs) × 5 |
Total: Sum of all categories (max 100)
Note: Structure Compliance is a blocking check. If structure validation fails (REV-STR001), the review cannot pass regardless of other scores.
Thresholds:
- PASS: ≥ 90 (configurable)
- WARNING: 80-89
- FAIL: < 80
评分公式:
| 分类 | 权重 | 计算方式 |
|---|---|---|
| 链接完整性 | 10% | (有效链接数 / 总链接数) × 10 |
| 阈值一致性 | 10% | (一致阈值数 / 总阈值数) × 10 |
| BRD对齐度 | 18% | (对齐需求数 / 总需求数) × 18 |
| 占位符检测 | 10% | (无占位符则得10分，否则10 - (占位符数量 × 2)) |
| 可追溯标签 | 10% | (有效标签数 / 总标签数) × 10 |
| 章节完整性 | 10% | (完整章节数 / 总章节数) × 10 |
| 客户端内容 | 5% | (存在且有实质内容得5分，否则0分) |
| 命名合规性 | 10% | (有效ID数 / 总ID数) × 10 |
| 结构合规性 | 12% | (嵌套文件夹有效得12分，否则0分) - 阻断性 |
| 上游漂移 | 5% | (最新引用数 / 总引用数) × 5 |
总分：所有分类得分之和（满分100）
说明：结构合规性为阻断性检查。如果结构校验不通过（REV-STR001），无论其他得分如何，审核都无法通过。
阈值:
- 通过：≥ 90（可配置）
- 警告：80-89
- 不通过：< 80
Command Usage
命令使用
Basic Usage
基础用法
bash
undefinedbash
undefinedReview specific PRD
审核指定PRD
/doc-prd-reviewer PRD-01
/doc-prd-reviewer PRD-01
Review PRD by path
按路径审核PRD
/doc-prd-reviewer docs/02_PRD/PRD-01_f1_iam/
/doc-prd-reviewer docs/02_PRD/PRD-01_f1_iam/
Review all PRDs
审核所有PRD
/doc-prd-reviewer all
undefined/doc-prd-reviewer all
undefinedOptions
选项
| Option | Default | Description |
|---|---|---|
| 90 | Minimum passing review score |
| true | Apply automatic fixes |
| false | Disable auto-fix (report only) |
| all | Specific checks to run (comma-separated) |
| none | Checks to skip (comma-separated) |
| false | Detailed output per check |
| true | Generate markdown report |
| auto | Report location (auto = alongside document) |
| auto | Review version (auto = auto-increment) |
| 选项 | 默认值 | 描述 |
|---|---|---|
| 90 | 审核通过的最低评分 |
| true | 应用自动修复 |
| false | 禁用自动修复（仅生成报告） |
| all | 要运行的指定检查项（逗号分隔） |
| none | 要跳过的检查项（逗号分隔） |
| false | 每个检查项输出详细信息 |
| true | 生成markdown报告 |
| auto | 报告存放位置（auto = 与文档同目录） |
| auto | 审核版本（auto = 自动递增） |
Examples
示例
bash
undefinedbash
undefinedReview with verbose output
审核时输出详细信息
/doc-prd-reviewer PRD-01 --verbose
/doc-prd-reviewer PRD-01 --verbose
Report only (no auto-fix)
仅生成报告（不自动修复）
/doc-prd-reviewer PRD-01 --no-auto-fix
/doc-prd-reviewer PRD-01 --no-auto-fix
Run only specific checks
仅运行指定检查项
/doc-prd-reviewer PRD-01 --check links,placeholders
/doc-prd-reviewer PRD-01 --check links,placeholders
Skip customer content check
跳过客户端内容检查
/doc-prd-reviewer PRD-01 --skip customer
/doc-prd-reviewer PRD-01 --skip customer
Lower threshold for draft review
降低草稿审核的阈值
/doc-prd-reviewer PRD-01 --min-score 80
---/doc-prd-reviewer PRD-01 --min-score 80
---Configuration
配置
yaml
undefinedyaml
undefinedconfig/prd_reviewer.yaml
config/prd_reviewer.yaml
prd_reviewer:
version: "1.0"
scoring:
min_score: 90
weights:
link_integrity: 15
threshold_consistency: 20
brd_alignment: 25
placeholder_detection: 15
traceability_tags: 10
section_completeness: 10
customer_content: 5
checks:
links:
enabled: true
check_external: false
auto_fix: true
thresholds:
enabled: true
source_priority: brd # brd or prd
auto_fix: true
alignment:
enabled: true
allow_orphans: false
require_deferral_notes: true
placeholders:
enabled: true
patterns:
- "[TODO]"
- "[TBD]"
- "[PLACEHOLDER]"
- "YYYY-MM-DDTHH:MM:SS"
- "[Name]"
auto_fix_dates: true
auto_fix_names: true
traceability:
enabled: true
allow_forward_refs: true
auto_fix_typos: true
completeness:
enabled: true
min_words:
executive_summary: 100
problem_statement: 75
functional_requirements: 200
quality_attributes: 100
customer_content: 100
risk_assessment: 75
appendices: 200
customer:
enabled: true
flag_always: true
jargon_patterns:
- "OIDC"
- "mTLS"
- "JWT"
- "4D Matrix"
output:
report_format: markdown
report_path: auto # auto = alongside reviewed document
versioning:
enabled: true
pattern: "_vNNN" # e.g., _v001, _v002
auto_increment: true
include_line_numbers: true
include_fix_diff: true
include_delta_report: true # Compare with previous version
---prd_reviewer:
version: "1.0"
scoring:
min_score: 90
weights:
link_integrity: 15
threshold_consistency: 20
brd_alignment: 25
placeholder_detection: 15
traceability_tags: 10
section_completeness: 10
customer_content: 5
checks:
links:
enabled: true
check_external: false
auto_fix: true
thresholds:
enabled: true
source_priority: brd # brd or prd
auto_fix: true
alignment:
enabled: true
allow_orphans: false
require_deferral_notes: true
placeholders:
enabled: true
patterns:
- "[TODO]"
- "[TBD]"
- "[PLACEHOLDER]"
- "YYYY-MM-DDTHH:MM:SS"
- "[Name]"
auto_fix_dates: true
auto_fix_names: true
traceability:
enabled: true
allow_forward_refs: true
auto_fix_typos: true
completeness:
enabled: true
min_words:
executive_summary: 100
problem_statement: 75
functional_requirements: 200
quality_attributes: 100
customer_content: 100
risk_assessment: 75
appendices: 200
customer:
enabled: true
flag_always: true
jargon_patterns:
- "OIDC"
- "mTLS"
- "JWT"
- "4D Matrix"
output:
report_format: markdown
report_path: auto # auto = alongside reviewed document
versioning:
enabled: true
pattern: "_vNNN" # e.g., _v001, _v002
auto_increment: true
include_line_numbers: true
include_fix_diff: true
include_delta_report: true # Compare with previous version
---Output Report
输出报告
File Naming & Versioning
文件命名与版本控制
Pattern:
PRD-NN.R_review_report_vNNN.mdNested Folder Rule: ALL PRDs use nested folders () regardless of size. This ensures review reports, fix reports, and drift cache files are organized with their parent document.
PRD-NN_{slug}/Location: Inside the PRD nested folder:
docs/02_PRD/PRD-NN_{slug}/Versioning Rules:
- First Review: Creates
PRD-NN.R_review_report_v001.md - Subsequent Reviews: Auto-increments version (v002, v003, etc.)
- Same-Day Reviews: Each review gets unique version number
Example Directory:
docs/02_PRD/PRD-01_f1_iam/
├── PRD-01.0_index.md
├── PRD-01.R_review_report_v001.md # First review
├── PRD-01.R_review_report_v002.md # After fixes
└── PRD-01.R_review_report_v003.md # Final review命名规则：
PRD-NN.R_review_report_vNNN.md嵌套文件夹规则：所有PRD无论大小都使用嵌套文件夹（），确保审核报告、修复报告和漂移缓存文件与父文档放在一起统一管理。
PRD-NN_{slug}/存放位置：PRD嵌套文件夹内部：
docs/02_PRD/PRD-NN_{slug}/版本控制规则:
- 首次审核：创建
PRD-NN.R_review_report_v001.md - 后续审核：版本自动递增（v002、v003等）
- 同日多次审核：每次审核都生成唯一版本号
目录示例:
docs/02_PRD/PRD-01_f1_iam/
├── PRD-01.0_index.md
├── PRD-01.R_review_report_v001.md # 首次审核
├── PRD-01.R_review_report_v002.md # 修复后审核
└── PRD-01.R_review_report_v003.md # 最终审核Report Structure
报告结构
markdown
undefinedmarkdown
undefinedPRD Review Report: PRD-01 (v003)
PRD审核报告: PRD-01 (v003)
Review Date: 2026-02-08T14:30:00
Review Version: v003
PRD: PRD-01 (F1 Identity & Access Management)
Status: PASS
Review Score: 95/100
审核日期: 2026-02-08T14:30:00
审核版本: v003
PRD: PRD-01 (F1身份与访问管理)
状态: 通过
审核评分: 95/100
Summary
汇总
| Check | Status | Score | Issues |
|---|---|---|---|
| Link Integrity | PASS | 15/15 | 0 |
| Threshold Consistency | PASS | 20/20 | 0 |
| BRD Alignment | PASS | 23/25 | 2 deferred |
| Placeholder Detection | PASS | 15/15 | 0 |
| Traceability Tags | PASS | 10/10 | 0 |
| Section Completeness | PASS | 10/10 | 0 |
| Customer Content | FLAG | 2/5 | Needs review |
| Total | PASS | 95/100 |
| 检查项 | 状态 | 得分 | 问题数 |
|---|---|---|---|
| 链接完整性 | 通过 | 15/15 | 0 |
| 阈值一致性 | 通过 | 20/20 | 0 |
| BRD对齐度 | 通过 | 23/25 | 2个延期项 |
| 占位符检测 | 通过 | 15/15 | 0 |
| 可追溯标签 | 通过 | 10/10 | 0 |
| 章节完整性 | 通过 | 10/10 | 0 |
| 客户端内容 | 待审核 | 2/5 | 需要审核 |
| 总分 | 通过 | 95/100 |
Issues Detail
问题详情
Flagged for Manual Review
标记为需人工审核
| File | Line | Issue | Code |
|---|---|---|---|
| PRD-01.10_customer_content.md | 42 | Technical jargon: "4D Matrix" | REV-C003 |
| PRD-01.10_customer_content.md | 58 | Technical jargon: "OIDC" | REV-C003 |
| PRD-01.10_customer_content.md | - | Requires marketing review | REV-C004 |
| 文件 | 行号 | 问题 | 错误码 |
|---|---|---|---|
| PRD-01.10_customer_content.md | 42 | 技术术语: "4D Matrix" | REV-C003 |
| PRD-01.10_customer_content.md | 58 | 技术术语: "OIDC" | REV-C003 |
| PRD-01.10_customer_content.md | - | 需要营销审核 | REV-C004 |
Auto-Fixes Applied
已应用的自动修复
| File | Line | Fix | Code |
|---|---|---|---|
| PRD-01.1_document_control.md | 15 | Date: YYYY-MM-DDTHH:MM:SS → 2026-02-08T14:30:00 | REV-P003 |
| 文件 | 行号 | 修复内容 | 错误码 |
|---|---|---|---|
| PRD-01.1_document_control.md | 15 | 日期: YYYY-MM-DDTHH:MM:SS → 2026-02-08T14:30:00 | REV-P003 |
Deferred Items (Acceptable)
延期项（可接受）
| Requirement | Reason | Note |
|---|---|---|
| BRD.01.01.10 | Device Trust | Marked P3, next cycle |
| BRD.01.01.12 | Time-Based Access | Marked P3, next cycle |
| 需求 | 原因 | 备注 |
|---|---|---|
| BRD.01.01.10 | 设备信任 | 标记为P3，下个迭代实现 |
| BRD.01.01.12 | 基于时间的访问 | 标记为P3，下个迭代实现 |
Recommendations
建议
- Section 10 Review: Schedule marketing review for customer-facing content
- Technical Terms: Consider adding glossary link for "4D Matrix", "OIDC"
- Deferred Items: Confirm P3 priority with stakeholders
Generated By: doc-prd-reviewer v1.1
Report Location: docs/02_PRD/PRD-01_f1_iam/PRD-01.R_review_report_v003.md
Previous Review: v002 (Score: 91/100)
undefined- 第10节审核：安排营销团队审核面向客户端的内容
- 技术术语：考虑为"4D Matrix"、"OIDC"添加术语表链接
- 延期项：与利益相关方确认P3优先级
生成工具: doc-prd-reviewer v1.1
报告位置: docs/02_PRD/PRD-01_f1_iam/PRD-01.R_review_report_v003.md
上次审核: v002 (得分: 91/100)
undefinedDelta Reporting
差异报告
When previous reviews exist, include score comparison:
markdown
undefined如果存在之前的审核记录，包含得分对比：
markdown
undefinedScore Comparison (v002 → v003)
得分对比（v002 → v003）
| Metric | Previous (v002) | Current (v003) | Delta |
|---|---|---|---|
| Overall Score | 91 | 95 | +4 |
| Errors | 2 | 0 | -2 |
| Warnings | 5 | 3 | -2 |
| Issues Resolved | - | 4 | - |
| New Issues | - | 0 | - |
See `REVIEW_DOCUMENT_STANDARDS.md` for complete versioning requirements.
---| 指标 | 上次（v002） | 当前（v003） | 变化 |
|---|---|---|---|
| 总得分 | 91 | 95 | +4 |
| 错误数 | 2 | 0 | -2 |
| 警告数 | 5 | 3 | -2 |
| 已解决问题 | - | 4 | - |
| 新增问题 | - | 0 | - |
完整版本控制要求请参见`REVIEW_DOCUMENT_STANDARDS.md`。
---Integration with doc-prd-autopilot
与doc-prd-autopilot的集成
This skill is automatically invoked during Phase 5 of :
doc-prd-autopilotmermaid
flowchart LR
A[Phase 4: Validation] --> B[Phase 5: Final Review]
B --> C{doc-prd-reviewer}
C --> D[Phase 6: Continue]Autopilot Integration:
yaml
undefined本工具会在的第5阶段自动调用：
doc-prd-autopilotmermaid
flowchart LR
A[第4阶段: 校验] --> B[第5阶段: 最终审核]
B --> C{doc-prd-reviewer}
C --> D[第6阶段: 继续流程]自动 pilot 集成配置:
yaml
undefinedIn doc-prd-autopilot config
In doc-prd-autopilot config
review:
enabled: true
skill: doc-prd-reviewer
options:
min_score: 90
auto_fix: true
flag_customer_content: true
---review:
enabled: true
skill: doc-prd-reviewer
options:
min_score: 90
auto_fix: true
flag_customer_content: true
---Standalone vs Integrated Use
独立使用 vs 集成使用
| Use Case | Command | Notes |
|---|---|---|
| After autopilot | Automatic | Invoked as Phase 5 |
| Manual PRD edit | | Run explicitly |
| Pre-EARS check | | Verify before EARS |
| Periodic audit | | Review all PRDs |
| 使用场景 | 命令 | 备注 |
|---|---|---|
| 自动 pilot 运行后 | 自动执行 | 作为第5阶段调用 |
| 手动编辑PRD后 | | 显式运行 |
| EARS生成前检查 | | 生成EARS前校验 |
| 定期审计 | | 审核所有PRD |
Error Recovery
错误恢复
Common Issues
常见问题
| Error | Cause | Resolution |
|---|---|---|
| PRD path invalid | Check path or PRD ID |
| BRD source missing | Verify BRD exists for alignment check |
| Score below threshold | Fix flagged issues |
| 错误 | 原因 | 解决方案 |
|---|---|---|
| PRD路径无效 | 检查路径或PRD ID |
| BRD源缺失 | 确认对齐检查所需的BRD存在 |
| 得分低于阈值 | 修复标记的问题 |
Recovery Commands
恢复命令
bash
undefinedbash
undefinedRe-run after fixes
修复后重新运行
/doc-prd-reviewer PRD-01
/doc-prd-reviewer PRD-01
Run with lower threshold (for drafts)
降低阈值运行（适用于草稿）
/doc-prd-reviewer PRD-01 --min-score 75
/doc-prd-reviewer PRD-01 --min-score 75
Skip failing check temporarily
临时跳过失败的检查项
/doc-prd-reviewer PRD-01 --skip alignment
---/doc-prd-reviewer PRD-01 --skip alignment
---Related Skills
相关工具
| Skill | Relationship |
|---|---|
| Naming standards for Check #8 |
| Invokes this skill in Phase 5 |
| Structural validation (Phase 4) |
| Applies fixes based on review findings |
| PRD creation rules |
| BRD source validation |
| Downstream consumer |
| 工具 | 关系 |
|---|---|
| 检查项8的命名标准 |
| 在第5阶段调用本工具 |
| 结构校验（第4阶段） |
| 根据审核结果应用修复 |
| PRD创建规则 |
| BRD源校验 |
| 下游消费者 |
Version History
版本历史
| Version | Date | Changes |
|---|---|---|
| 1.6 | 2026-02-11 | Numbering Fix: Corrected Check #10 subsections from 9.1-9.6 to 10.1-10.6 (drift cache, detection algorithm, hash calculation, error codes, report output, configuration) |
| 1.5 | 2026-02-11 | Structure Compliance: Added Check #9 for nested folder rule enforcement (REV-STR001-STR004); Shifted Upstream Drift to Check #10; Added structure compliance to scoring (12% weight, blocking); Updated workflow diagram to 10 checks |
| 1.4 | 2026-02-10T17:00:00 | Mandatory drift cache: Reviewer MUST create/update |
| 1.3 | 2026-02-10 | Added Check #9: Upstream Drift Detection - detects when BRD documents modified after PRD creation; REV-D001-D005 error codes; drift configuration; Added doc-prd-fixer to related skills |
| 1.2 | 2026-02-10 | Added review versioning support (_vNNN pattern); Delta reporting for score comparison |
| 1.1 | 2026-02-08 | Added Check #8: Naming Compliance (doc-naming integration) |
| 1.0 | 2026-02-08 | Initial skill creation with 7 review checks |
| 版本 | 日期 | 变更内容 |
|---|---|---|
| 1.6 | 2026-02-11 | 编号修复：将检查项10的子章节编号从9.1-9.6修正为10.1-10.6（漂移缓存、检测算法、哈希计算、错误码、报告输出、配置） |
| 1.5 | 2026-02-11 | 结构合规性：新增检查项9用于强制嵌套文件夹规则（REV-STR001-STR004）；将上游漂移检测移至检查项10；将结构合规性纳入评分（权重12%，阻断性）；更新工作流图为10个检查项 |
| 1.4 | 2026-02-10T17:00:00 | 强制漂移缓存：审核工具每次审核后必须创建/更新 |
| 1.3 | 2026-02-10 | 新增检查项9：上游漂移检测——检测BRD文档在PRD创建后是否被修改；REV-D001-D005错误码；漂移配置；将doc-prd-fixer加入相关工具 |
| 1.2 | 2026-02-10 | 新增审核版本控制支持（_vNNN模式）；得分对比差异报告 |
| 1.1 | 2026-02-08 | 新增检查项8：命名合规性（与doc-naming集成） |
| 1.0 | 2026-02-08 | 工具首次发布，包含7个审核检查项 |