doc-review

用途

doc-review 是一个文档审查 Skill，通过 Codex exec 对 Markdown 文档进行评审。其触发关键词包括：review doc、document review、tech spec review、review-spec、doc-refactor、streamline doc。

明确不适用的情况：

• 代码审查（应使用 codex-code-review）
• 测试覆盖率审查（应使用 test-review）
• 只是想阅读文档（直接使用 Read）

主要能力

提供以下命令：

命令	说明	使用场景
/codex-review-doc	Codex 审查 .md 文档	文档变更
/review-spec	审查技术规格	规格确认
/doc-refactor	精简文档	文档过长
/update-docs	研究并更新文档	代码变更之后

审查维度包括：

• 架构设计：系统边界、职责、依赖、可扩展性
• 性能：瓶颈、并发、缓存、资源使用
• 安全：数据泄漏、访问控制、输入校验、错误处理
• 文档质量：结构、完整性、准确性、示例、文档写作标准
• 代码一致性：伪代码与代码库是否一致、引用的文件是否存在、技术准确性

使用方式

工作流 /codex-review-doc 的步骤为：目标集 → 确定性检查 → 解析配置与批次 → 逐批 Codex 审查 → 评分表与门禁 → 循环。

1. 确定目标集：若指定路径则全部作为同一计划使用；未指定路径则通过 git diff --name-only HEAD 及未跟踪文件过滤出 .md；若无变更则报告并停止。不得将多文件变更收窄为单文件。

2. 先做确定性检查：

node scripts/check-doc-links.js --root "$(git rev-parse --show-toplevel)" <changed .md paths>

该检查为建议性输入而非门禁，始终以 0 退出。它只扫描工作树中存在的路径，已删除的 .md 会被省略。需同时传入 failures 与 unresolved 两个字段，仅当 unresolved 为 0 时 failures: [] 才能确定链接问题。

1. 解析配置与批次：

node scripts/resolve-review-profile.js --tier <effective tier> --files <a.md,b.md> --root "$(git rev-parse --show-toplevel)"

该步骤决定三件事且之后不可更改：配置在构建提示词之前解析；升级是单向且按文件的；超预算的计划会显式拆分。

1. 逐批 Codex 审查：首次审查按 @skills/codex-code-review/references/codex-transport.md § Start 分发文档审查提示词（见 references/codex-prompt-doc.md），保存返回的 threadId（每批一个）。循环审查按 § Resume 使用复审模板（见 references/review-loop-doc.md）。codex_fail 时走回退流程，通过 scripts/lib/review-dispatch.js 决定，记录 [REVIEWER_FALLBACK] 标记，并通过 Task 分发 contract-neutral-reviewer，用 node scripts/validate-family-sentinel.js doc 校验原始报告。

2. 汇总输出：整理为评分表 + 按严重度分组的问题 + 门禁。整个计划只有一个门禁：任一批次返回 ⛔ Needs revision 即阻塞该计划。

审查循环：⛔ Needs revision → 修复 🔴 项 → /codex-review-doc --continue <threadId> → 重复直到 ✅ Mergeable。轮次预算为该 tier 的上限（fast 上限为 6，文档是该 tier 的主要场景；rules/auto-loop-project.md 中显式的 ## Max Rounds 可覆盖）。仅 🔴 阻塞，🟡 和 ⚪ 不阻塞。

审查配置

由 scripts/resolve-review-profile.js 解析，不在分发时手动选择：

配置	使用时机	审查者阅读内容	问题
full-design	设计落地前；未知分类；安全/数据完整性；任何升级	整个变更文档 + 关联设计上下文	全部五个维度
implementation-sync	代码落地后更新的当前权威文档	变更片段 + 所属 ## 章节 + 前言 + 链接定义	被审查章节是否与实现矛盾？受影响的交叉引用是否失效？
living-sync	当前权威文档，仅文档编辑	变更章节	准确性与内部一致性
record-diff	设计/工作/历史记录	变更片段	编辑是否内部连贯并正确标记为记录？无代码对齐义务
executable	指令表面（skills/、rules/）	变更章节 + 文件自身契约	指令是否仍可执行？是否有冲突指令？

新增（未跟踪）文件在任何配置下都整篇阅读。配置只收窄审查者阅读范围，从不决定是否运行审查，且任何解析结果都不会自动通过。

适用场景

• 审查 .md 文档变更
• 技术规格审计与确认
• 文档质量检查
• 文档过长时进行精简
• 代码变更后研究并更新文档

限制

• 不用于代码审查（使用 codex-code-review）
• 不用于测试覆盖率审查（使用 test-review）
• 仅用于阅读文档时直接使用 Read
• 链接检查器是扫描器而非 CommonMark 解析器，标题片段不在其范围内；当 unresolved > 0 时，相应数量的链接形态未被检查
• 回退代理是无状态的，每轮循环都是全新分发
• 关于收费、价格、平台支持等具体信息，资料中暂未提供

验证要求

• 每个问题都标注严重度（🔴/🟡/⚪）
• 门禁明确（✅ Mergeable / ⛔ Needs revision）
• Codex 独立验证代码与文档一致性

必需操作

变更类型	必须执行
.md 文档	/codex-review-doc 或 /review-spec
技术规格	/review-spec
README	/codex-review-doc

参考

• 文档审查提示词：references/codex-prompt-doc.md
• 审查循环：references/review-loop-doc.md
• 配置解析器：scripts/resolve-review-profile.js
• 链接检查器：scripts/check-doc-links.js
• 标准：@rules/docs-writing.md