Back to Details

review-doc-consistency

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Consistency Reviewer

文档一致性审查器

Goal

目标

Systematically identify all "outdated" or "inconsistent with implementation" descriptions in README + docs/, outputting ≥30 issue items.
系统性识别README和docs/中所有“过时”或“与实现逻辑不一致”的描述，输出不少于30个问题项。

Core Principles

核心原则

  1. Code is truth - When documentation conflicts with code, source code/config/contract files are authoritative
  2. Evidence before conclusions - Each issue must cite code/config location as evidence
  3. Contracts first - OpenAPI/proto/schema/TS types are treated as SSOT (Single Source of Truth)
  4. Security default tightening - Security-related inconsistencies are prioritized as high severity
  1. 代码为基准 - 当文档与代码存在冲突时，源代码/配置/契约文件为权威依据
  2. 结论基于证据 - 每个问题必须引用代码/配置位置作为证据
  3. 契约优先 - OpenAPI/proto/GraphQL schema/TS types 被视为SSOT（单一可信源）
  4. 安全默认收紧 - 与安全相关的不一致问题被列为高优先级

Review Process

审查流程

1. Document Enumeration

1. 文档枚举

bash
undefined
bash
undefined

Scan scope

扫描范围

  • README.md (root directory)
  • docs/**/*.md (all documentation)
  • Contract files: OpenAPI/proto/GraphQL schema/TS types
undefined
  • README.md（根目录）
  • docs/**/*.md（所有文档）
  • 契约文件：OpenAPI/proto/GraphQL schema/TS types
undefined

2. Document-by-Document Review

2. 逐文档审查

For each document:
  1. List key claims/commitments/configs/interface items
  2. Search for corresponding implementation in code
  3. Compare differences: missing/renamed/behavior mismatch/default value mismatch
  4. Record issues using template
针对每个文档：
  1. 列出关键声明/承诺/配置/接口项
  2. 在代码中查找对应的实现逻辑
  3. 对比差异：缺失/重命名/行为不匹配/默认值不匹配
  4. 使用模板记录问题

3. Cross-Check

3. 交叉核查

  • Reverse check documentation from contract files
  • Reverse check documentation from config files
See checklist.md for detailed review checklist.
  • 从契约文件反向核查文档
  • 从配置文件反向核查文档
详情请查看checklist.md中的详细审查清单。

Severity Levels

严重等级

LevelDefinitionExample
P0Security issue/serious misleadingDocs say sandbox enabled but code doesn't enable it
P1Core functionality inconsistencyFollowing docs leads to failure
P2Incomplete examples/naming inconsistencyDoesn't directly block usage
P3Wording/formatting/link minor issuesDoesn't affect functionality
Pending EvidenceSuspicious but insufficient evidenceNeeds further investigation
等级定义示例
P0安全问题/严重误导文档显示已启用沙箱但代码未启用
P1核心功能不一致按照文档操作会导致失败
P2示例不完整/命名不一致不会直接阻碍使用
P3措辞/格式/链接小问题不影响功能
待确认证据存在疑点但证据不足需要进一步调查

Output Format

输出格式

See output-format.md for detailed templates.
详情请查看output-format.md中的详细模板。

Single Issue Item

单个问题项

markdown
undefined
markdown
undefined

[Title]

[标题]

  • Severity: P0/P1/P2/P3/Pending Evidence
  • Location: 
    <file_path>:<line_number>
  • Evidence:
    • Documentation: [quote]
    • Code: [quote]
  • Impact: [Misleading consequences]
  • Suggestion: [Minimal fix]
  • Related Principle: Code is truth/Contracts first/Security default tightening/...
undefined
  • 严重等级: P0/P1/P2/P3/待确认证据
  • 位置: 
    <文件路径>:<行号>
  • 证据:
    • 文档: [引用内容]
    • 代码: [引用内容]
  • 影响: [误导性后果]
  • 建议: [最小修复方案]
  • 相关原则: 代码为基准/契约优先/安全默认收紧/...
undefined

Review Conclusion

审查结论

markdown
undefined
markdown
undefined

Review Conclusion

审查结论

  • Verdict: Pass/Conditional Pass/Fail
  • Summary: P0:x P1:x P2:x P3:x Pending:x
  • Fix Priority: P0 → P1 → P2 → P3
undefined
  • ** verdict**: 通过/有条件通过/不通过
  • 摘要: P0:x P1:x P2:x P3:x 待确认:x
  • 修复优先级: P0 → P1 → P2 → P3
undefined

Multi-Agent Parallel

多Agent并行处理

For acceleration, split by following dimensions for parallel multi-agent execution:
  1. By document type - One agent each for README, API docs, development guide
  2. By module - One agent per functional module's documentation
  3. By check direction - One checks docs against code, another checks code against docs
Deduplication and unified severity rating needed when aggregating.
为提升效率，可按以下维度拆分任务进行多Agent并行执行：
  1. 按文档类型 - 分别为README、API文档、开发指南分配一个Agent
  2. 按模块 - 每个功能模块的文档分配一个Agent
  3. 按检查方向 - 一个Agent负责文档对照代码检查，另一个负责代码对照文档检查
聚合结果时需要进行去重和统一严重等级评定。

Execution

执行步骤

After review completion, output 
doc-consistency.md
report file, and also output 
doc-consistency.json
(structured issue list for aggregation/deduplication/statistics).
审查完成后，输出
doc-consistency.md
报告文件，同时输出
doc-consistency.json
（结构化问题列表，用于聚合/去重/统计）。