doc-quality-review

name	doc-quality-review
description	将粗略学习笔记转化为结构清晰的文档。核心能力：设计思维导图风格的 TOC 标题（命令/API/配置项 + 功能描述），让读者仅扫描目录即可定位具体操作，无需跳转正文；同时处理内容补充、代码增强、格式规范、技术校验。适用于 `docs/` 下所有手写笔记，无论输入是零散要点还是半成品。触发词：审查文档、整理笔记、润色粗稿、review doc、质量检查、doc audit、文档审查、文档质量、检查笔记、优化笔记。

文档质量审查与增强

处理 docs/ 下的笔记，无论输入是零散要点、粗略草稿还是半成品。TOC 标题思维导图化是最高优先级——让目录本身就是可扫描的速查表。

核心原则

• 不扩展（最高约束）：严格基于已有内容优化，不自行添加新主题、新命令、新概念。改进只发生在用户已记录的内容范围内——润色表述、规范标题、补注释、修格式。如果发现值得扩展的点，标记为「扩展建议」，用 AskUserQuestion 征得用户同意后才新增标题节点或内容段落
• TOC 标题：基于已有内容设计思维导图风格的标题，展示给用户确认后才写入
• 格式排版：自动修复，无需确认
• 代码增强（补注释、补示例）：在已有代码块基础上增强，自动执行，完成后汇总
• 技术事实：查证后直接修正错误
• 内容态度：保留用户原文核心描述，只补充不重写

报告和输出中，强调内容用反引号（`）包裹。结构标签仍用加粗。

工作流程

第一步：确认范围

用 AskUserQuestion 确认：

1. 目标文件：具体路径，或「最近修改的文档」
2. 审查模式：
   • 全量审查：整个文件（默认）
   • 增量审查：仅 git diff 变更的 H2/H3 区间

第二步：并行收集数据

同时发起以下调用：

• Read 读取目标文档全文
• Grep 提取所有 H2/H3/H4 标题（^#{2,4} ）
• Grep 提取 --8<-- 代码引用
• Read 读取 zensical.toml 的 nav 部分
• explore agent（后台）验证代码引用文件是否存在

第三步：TOC 设计（核心，最高优先级）

好的 TOC 让读者仅扫描右侧目录就能定位具体操作。这是本 skill 最重要的环节。

标题模式

标题承载两类信息：定位符（具体的命令/API/配置名，让读者快速定位）和语义描述（一句话说明它做什么，让读者判断是否需要深入阅读）。

标题类型	格式	示例
命令	命令-功能描述	git add-将文件添加到暂存区
API / 注解	名称-作用描述	@EnableWebSecurity-启用 Web 安全
配置项	配置键-作用描述	server.port-服务监听端口
概念	纯名称，可附英文	暂存区（Staging Area）
分组 / 分类	描述性短语	文件状态、三个区域

设计规则

1. 命令标题必须包含完整名称（git add，不是 add）
2. 描述部分简洁，≤15 字
3. 同一命令的不同场景可拆分为多个标题（如 git add-添加新文件 和 git add-添加已修改文件）
4. 概念标题不加具体操作，保持抽象
5. H2 划分知识维度，H3 拆分具体知识点，H4 用于细分变体
6. H4 在 zensical TOC 中不可见——如果某 H3 下 ≥3 个 H4 且内容独立，建议提升为 H3
7. 同级标题保持对齐：同为命令型或同为概念型，避免混杂导致扫描不连贯

执行流程

1. 从已有内容中提取所有命令、API、配置项、概念
2. 基于提取到的内容设计 TOC 层级：
   • 无标题的粗稿：将已有要点组织为完整 TOC，每个标题必须对应用户已记录的内容
   • 有标题的半成品：按模式规则改进已有标题
3. 常见问题检查：
   • 命令标题缺少定位符（添加文件到暂存区 → git add-添加文件到暂存区）
   • 孤立术语（概述 → Docker 网络概述）
   • 万能标题反复出现（多处 其他、总结）
   • 扁平清单（≥5 个连续 H2 无 H3 → 按逻辑分组）
4. 扩展建议（可选）：如果发现用户的内容存在明显的知识缺口（如讲了 git add 和 git commit 但跳过了 git status），在 TOC 末尾单独列出「💡 扩展建议」，用 AskUserQuestion 征求用户意见。用户确认后才新增对应的标题节点和内容
5. 用 AskUserQuestion 展示设计的完整 TOC（含扩展建议）和改动说明
6. 用户确认后进入下一阶段

标题改进示例

🟠 `## 概述` → `## Docker 网络概述`（消除孤立术语）
🟠 `### 添加文件` → `### git add-将文件添加到暂存区`（补充命令定位符）
🟠 `## 其他` → `## 高级用法`（替换万能标题）

第四步：内容增强

根据确认的 TOC 逐节处理。

代码注释（自动，基于已有代码）

• ≥3 行无注释代码块：为关键行加中文注释
• 纯占位符语法（xxx、<placeholder>）：用真实参数替换，追加具体示例
• 不新增用户未提及的命令或 API——只为已有的代码块添加注释和示例变体

增强示例：

原文：

git add <file>

增强后：

# 将指定文件添加到暂存区
git add <file>

追加示例：

git add README.md    # 添加单个文件
git add .            # 添加所有修改
git add -p           # 交互式选择

内容清晰度

• 代码块前至少一句引导说明
• 术语首次出现时有解释
• 保留用户原文核心描述，润色表述但不改写
• 不自行添加用户未提及的知识点或段落

第五步：格式合规（自动修复）

规范	说明
代码块 ``` 后有空格（带属性时）	```java → ``` java
Admonition 空行 + 4 格缩进	!!! 标题行后必须空行，内容缩进 4 格
列表前有空行	段落与无序列表间必须空行
强调用反引号	**术语** → `术语`
图片用 <figure> 格式	禁止裸 ![]()
交叉引用用「」	"第X章" → 「章节名」
中文标点与间距	半角→全角、中英文间补空格、补句号

标点修复在汇总行注明数量，不逐条列出。

第六步：元数据与注册

1. 补充 front matter（title、icon 等）
2. title 必须与 zensical.toml nav 标题完全一致
3. 新增页面需在 nav 注册
4. 元数据修复前展示具体变更供确认

第七步：技术校验

准确性：

1. 提取关键技术断言（版本号、API 行为、默认值）
2. 先查本地缓存 .claude/doc-review-cache.json
3. 未命中 → Context7 查证（resolve-library-id → query-docs）
4. Context7 不可用 → WebSearch 查官方文档
5. 新验证事实追加到缓存

缓存格式：

{
  "facts": [
    {
      "assertion": "原文断言",
      "correct": "正确信息",
      "source": "Context7 / 官方文档",
      "verified_at": "2025-01-15"
    }
  ]
}

代码引用：--8<-- 路径和标记是否存在。

第八步：输出报告

# 文档审查报告：`文件路径`

> 审查日期：YYYY-MM-DD

## TOC 结构（X H2 / Y H3 / Z H4）

| # | 级别 | 标题 | 状态 |
|---|------|------|------|
| 1 | H2 | `三个区域` | ✅ |
| 2 | H3 | `git add-将文件添加到暂存区` | 🟠 已补充定位符 |

## 自动修复

- 格式排版：X 处
- 代码增强：X 处
- 技术修正：X 处

## 待确认

- 元数据修复（如有）

修复完成后执行 zensical build 验证站点构建。