# Doc Quality Review

> Doc Quality Review is an Agent Skill for documents published in the luguosong/programming-notes repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

- Skill name: `doc-quality-review`
- Category: [Documents](https://www.openparable.com/skill/documents/1)
- Source: https://github.com/luguosong/programming-notes/blob/HEAD/.claude/skills/doc-quality-review/SKILL.md
- Repository: luguosong/programming-notes (356 GitHub stars when collected)

## SKILL.md

# 文档质量审查与增强

处理 `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>
```

增强后：

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

追加示例：

```shell
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. 新验证事实追加到缓存

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

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

### 第八步：输出报告

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

> 审查日期：YYYY-MM-DD

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

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

## 自动修复

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

## 待确认

- 元数据修复（如有）
```

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

---

Source: https://www.openparable.com/skill/documents/doc-quality-review (OpenParable). Cite the canonical URL above.