Doc Quality Review

⚡ 效率关键：以下操作应尽量并行执行，不要串行等待。

同时发起以下调用：

• view 读取目标文档全文
• grep 提取所有 H2/H3 标题（^#{2,3} ）
• grep 提取所有 --8<-- 代码引用
• view 读取学习目标列表（🎯 本文你会学到 所在行）
• explore agent（后台）验证所有代码引用标记是否存在

第三步：执行审查（按以下 7 个维度检查）

⚡ 维度 1 的 Context7 查询与维度 5 的代码引用验证可并行。

审查维度 1：技术准确性

目标：确保文档中的 API 用法、版本号、类继承关系、方法签名、行为描述与官方文档一致。

方法：

1. 提取文档中涉及的核心技术断言（如「PrintStream 默认自动刷新」「Scanner 用正则做分词」）
2. 重点关注版本号声明 — 对所有形如「Java X 引入」「JDK X.Y 新增」「@Since: X」的断言，必须通过 Context7 查证 @Since 标签
3. 使用 Context7 MCP 查证关键事实：
   • 先调用 context7-resolve-library-id 解析库 ID（如 java → /websites/oracle_en_java_javase_21_api）
   • 再调用 context7-query-docs 查询具体 API 的 @Since 标签和行为描述
   • ⚡ 多个独立查询可并行发起
4. 对无法通过 Context7 查证的断言，使用 web_search 查找官方文档确认

常见错误模式：

已验证事实速查（减少重复查询）：

输出格式：

🔴 [准确性] 第 X 行：「原文引用」
   事实：<正确描述>（来源：Context7 @Since / 官方文档）
   修复建议：<具体修改>

审查维度 2：教学风格

目标：确保文档符合项目 CLAUDE.md 中定义的教学风格约束（仅适用于非翻译类内容）。

检查项：

豁免：docs/document-translation/ 下的翻译文档忠于原书风格，不审查教学风格。

输出格式：

🟡 [教学风格] 第 X 行 H3「标题名」：
   问题：<描述>
   建议：<改进方向>

审查维度 3：TOC 大纲结构

目标：确保标题层级 = 知识脉络，读者只看 TOC 就能理解文章推进逻辑。

检查项：

1. 提取所有 H2/H3 标题（用 grep 匹配 ^#{2,3} ）
2. 检查渐进逻辑：H2 从上到下是否体现知识阶段递进
3. 检查 H3 拆分：任何 H2 下涵盖 ≥3 个子概念时是否拆出 H3
4. 检查反模式：
   • 扁平清单（≥5 个连续 H2 无 H3）
   • 孤立术语（H2 标题为纯类名，无上下文）
   • 万能标题（反复出现「概述」「其他」「总结」）
   • 编号代替逻辑（「第一步」「第二步」）
5. ⚠️ 重点检查 H4 可见性：Zensical TOC 只显示 H2+H3，H4 在右侧目录中完全不可见。如果某个 H3 下有 ≥3 个 H4 子节且每个 H4 内容独立，应考虑将这些 H4 提升为 H3（父级 H3 提升为 H2）。这是实际审查中发现的高频问题。

命名风格检查：

输出格式：

🟠 [TOC 结构] H2「标题」：
   问题：<描述>（反模式：<模式名>）
   建议：<重构方案>

审查维度 4：学习目标完整性

目标：确保文档开头的「🎯 本文你会学到」列表与实际 H2 章节一一对应。

检查方法：

1. 提取「🎯 本文你会学到」列表中的条目
2. 提取所有 H2 标题
3. 交叉对比：
   • H2 有但列表中没有 → 遗漏
   • 列表中有但 H2 没有 → 空头承诺
   • 措辞不一致（如列表说「互转」但 H2 说「对比与互转」） → 措辞偏差

输出格式：

🔴 [学习目标] 遗漏：H2「WatchService——监控目录变化」未出现在学习目标列表中
🟡 [学习目标] 措辞偏差：列表「File 与 Path 的互转」 vs H2「File vs Path——对比与互转」

审查维度 5：代码引用有效性

目标：确保所有 --8<-- 代码片段引用指向存在的文件和标记。

检查方法：

1. 用 grep 提取文档中所有 --8<-- "..." 引用路径
2. 对每个路径检查文件是否存在（view 工具）
3. 如果引用包含标记名（:marker_name），检查目标文件中是否存在 // --8<-- [start:marker_name] 和 // --8<-- [end:marker_name]

输出格式：

🔴 [代码引用] 第 X 行：文件不存在 — "code/java/javase/io/io-xxx/..."
🔴 [代码引用] 第 X 行：标记不存在 — ":some_marker" 在目标文件中未找到

审查维度 6：排版风格一致性

目标：确保文档遵守 CLAUDE.md 中定义的排版约定。

检查项：

输出格式：

🟡 [排版] 第 X 行：技术术语「Authorization Code」使用了加粗而非反引号

审查维度 7：内容充实度

目标：确保每个章节都有足够的内容支撑，不存在「占位符式」的薄弱段落。

检查方法：

1. 逐个扫描 H2/H3 小节，计算每节的有效散文行数（排除空行、代码块、表格、图片）
2. 标记以下情况为「薄节」：
   • H2 小节有效散文 ≤ 3 行且无代码示例
   • H3 小节有效散文 ≤ 1 行且无代码示例
   • 某个技术概念只用一句话提及但没有展开解释或示例

严重程度判定：

输出格式：

🟡 [充实度] 第 X 行 H3「标题」：
   问题：仅有 1 句话（X 字），无代码示例
   建议：补充 What/Why/How 结构，或至少添加一个代码示例

第四步：生成审查报告

按以下表格格式汇总所有发现（比列表更清晰易读）：

# 📋 文档审查报告：<文件路径>

## 🔴 必须修复（X 处）

| # | 维度 | 行号 | 问题 | 修复建议 |
|---|------|------|------|---------|
| 1 | 准确性 | L333 | 版本号错误... | 改为... |

## 🟡 建议修复（X 处）

| # | 维度 | 行号 | 问题 | 修复建议 |
|---|------|------|------|---------|
| 1 | 充实度 | L472 | 内容过薄... | 补充... |

## ✅ 审查通过

| 维度 | 状态 | 详情 |
|------|------|------|
| 技术准确性 | ✅ 通过 | 查证了 X 个断言，均正确 |
| 教学风格 | ✅ 通过 | 类比+渐进+术语解释均到位 |
| TOC 结构 | ✅ 通过 | X H2 / Y H3，逻辑清晰 |
| 学习目标 | ✅ 通过 | X 条目标与 X 个 H2 对应 |
| 代码引用 | ✅ 通过 | X/X 引用验证通过 |
| 排版风格 | ✅ 通过 | 格式一致 |
| 内容充实度 | ✅ 通过 | 无薄节 |

第五步：修复

使用 ask_user 询问用户是否需要自动修复。如果用户确认：

1. 按严重程度从高到低修复
2. 每修复一处用 edit 工具直接更改
3. 修复完成后执行 zensical build 验证站点构建
4. 使用 git-commit skill 提交修复