improve-doc

改进文档

分析现有的 Markdown 文档，按 Diataxis 类型对各个章节进行分类，找出问题，并通过交互逐一改进。

参数

• 路径： 要改进的 Markdown 文档路径（必填）

工作流概览

使用文档路径调用 improve-doc 技能，例如 improve-doc docs/guides/getting-started.md。

该技能分两个阶段运行：

1. 分析阶段： 解析文档、分类各个章节、找出问题
2. 改进阶段： 通过交互循环逐一改进各个章节

阶段门槛

严格按顺序推进——只有满足通过条件（有相应产物或用户明确输入，不能自行假定）后才能继续。

进入第 2 阶段（改进）之前：

1. 读取 — 已加载路径指定文件的全部内容。
   • 通过： 枚举出的章节（依据 # / ## / ### 标题）涵盖文件中的所有标题；标题与原文一致。
2. 核心技能 — 在分类之前，已加载 docs-style（或已读取其路径）。
   • 通过： 分析输出体现了该技能至少一条具体原则（指出其名称或简要引用）。
3. 交接 — 用户已看到分析摘要（使用步骤 5 中的模板或同等内容），并输入 start 开始改进，或输入 abort 退出。
   • 通过： 如果输入 abort，不得写入路径指定的文件。如果输入 start，则进入第 2 阶段。

覆盖文件之前（第 2 阶段，步骤 4）：

1. 选择 — 每个存在未解决问题的章节都已确定最终处理方式：应用修改 yes、保持不变 skip，或通过 modify 循环后以 yes 或 skip 结束。
   • 通过： 不得有任何章节仍处于待处理的 modify 状态，除非用户中止了整个会话（此时不得写入）。
2. 跳过 — 每个选择 skip 的章节内容都与原始章节文本一致（保留原文副本，不得改写）。
   • 通过： 与初次读取的内容逐行完全一致，包括空白字符。
3. 写入 — 仅在满足上述条件后进行。
   • 通过： 仅保存一次到路径指定的文件；完成报告须在适用时说明备份或重大重组情况（见规则）。

Diataxis 类型不明确 — 如果无法确定分类，在用户回答澄清选项（步骤 2b）或明确确认你说明的默认选择之前，不得编辑该章节。

第 1 阶段：分析

步骤 1：读取文档

读取目标 Markdown 文件，并按标题解析为各个章节：

• 每个 #、##、### 标题都会开始一个新章节
• 记录标题级别、标题文本和内容
• 保留层级关系以提供上下文

步骤 2：加载核心技能

加载 docs-style，获取适用于所有文档类型的核心写作原则。

步骤 3：分类各个章节

根据以下指标确定每个章节的 Diataxis 类型（完整的判断流程和两个关键区别，请参阅 docs-style/references/diataxis-compass.md）：

类型	指标
教程	使用 “Let's”“we will”等表达；循序渐进地学习；逐步完成一个项目；很少解释原因
操作指南	标题为 “How to”；以任务为中心的步骤；假定读者已有相关知识；以目标为导向
参考	参数表、类型签名、API 规范、事实描述；没有叙述性内容
解释	“Why”“because”等表达；历史、权衡、替代方案、概念讨论

分类规则：

1. 首先检查标题——“How to X” 始终属于操作指南，“Why X” 始终属于解释
2. 查看结构模式——包含参数或类型的表格通常表示参考
3. 分析语言——面向学习（“Let's learn”）还是面向任务（“To accomplish X”）
4. 考虑上下文——该章节之前和之后的内容
5. 如果某个章节混合了多种类型，则标记为“混合”；这是需要解决的问题

步骤 4：识别问题

对于每个部分，根据检测到的类型检查问题：

教程问题：

• 解释“为什么”，而不是仅引导学习者操作
• 跳过步骤，假设读者具备先前知识
• 没有明确的学习成果
• 缺少“你将构建／学会……”的表述

操作指南问题：

• 包含离题的解释
• 缺少前置条件
• 步骤不够细化（每步包含多个操作）
• 没有验证目标是否达成

参考文档问题：

• 缺少参数类型或返回值
• 使用叙述性文字，而非事实性描述
• 选项／参数介绍不完整
• 没有代码示例

解释文档问题：

• 包含操作步骤
• 缺少“为什么”的背景说明
• 没有讨论权衡或替代方案
• 读起来像参考文档

跨类型问题（适用于任何部分）：

• 单个部分混杂多种 Diataxis 类型
• 未明确受众是谁
• 标题缺失或含糊
• 内容堆砌，缺乏结构

步骤 5：呈现分析

向用户显示分析摘要：

## Document Analysis

**File:** `docs/guides/getting-started.md`
**Sections found:** 8
**Estimated time:** ~15 minutes to refine

### Type Breakdown

| Type | Sections | Health |
|------|----------|--------|
| Tutorial | 2 | 1 issue |
| How-To | 3 | 4 issues |
| Reference | 1 | Clean |
| Explanation | 1 | 2 issues |
| Mixed | 1 | Needs split |

### Top Issues

1. **Section "Setting Up"** (How-To): Contains explanatory tangent about architecture
2. **Section "Configuration Options"** (Mixed): Blends reference table with tutorial steps
3. **Section "Authentication"** (How-To): Missing prerequisites, steps not atomic
4. **Section "Why We Built This"** (Explanation): Includes procedural steps

### Ready to Refine?

I'll go through each section with issues. For each one, you can:
- **yes** - Accept the proposed improvement
- **skip** - Keep original, move to next section
- **modify** - Tell me what to change about the proposal

Type "start" to begin refinement, or "abort" to exit without changes.

第 2 阶段：交互式优化

步骤 1：加载特定类型的技能

遇到每种部分类型时，如果尚未加载，则加载相关技能：

• 教程部分：tutorial-docs
• 操作指南部分：howto-docs
• 参考文档部分：reference-docs
• 解释文档部分：explanation-docs

步骤 2：优化循环

按文档顺序处理每个存在问题的部分：

2a：显示当前状态

---

## Section 3 of 5: "Setting Up" (How-To)

### Current Content

> ## Setting Up
>
> Before we begin, it's important to understand why the architecture
> works this way. The system uses a microservices pattern because...
> [explanatory content]
>
> To set up the project:
> 1. Clone the repo and install dependencies
> 2. Configure the environment variables
> 3. Start the server

### Issues Found

1. **Explanatory tangent** (lines 1-3): How-To should assume reader knows why; move explanation to dedicated Explanation section
2. **Non-atomic steps** (step 1): "Clone and install" is two actions; split into separate steps
3. **Missing verification**: No way to confirm setup succeeded

2b：提出澄清问题（如有需要）

如果类型分类不确定：

### Quick Question

This section has characteristics of both How-To (task steps) and Explanation (why content). How would you like to handle it?

1. **Split** - Create separate How-To and Explanation sections
2. **How-To** - Remove explanation, keep as pure How-To
3. **Explanation** - Remove steps, keep as pure Explanation

2c：提出改进方案

### Proposed Improvement

> ## Setting Up
>
> **Prerequisites:** Familiarity with microservices architecture
>
> ### Steps
>
> 1. Clone the repository
>    ```bash
>    git clone https://github.com/example/project.git
>    ```
>
> 2. Install dependencies
>    ```bash
>    cd project && npm install
>    ```
>
> 3. Configure environment variables
>    ```bash
>    cp .env.example .env
>    ```
>
> 4. Start the server
>    ```bash
>    npm start
>    ```
>
> ### Verify
>
> Open http://localhost:3000 - you should see the welcome page.

**Changes made:**
- Removed explanatory content (suggest creating "Architecture Overview" section)
- Split "clone and install" into separate steps
- Added verification step
- Added prerequisites reference

---

**Your choice:** [yes / skip / modify]

2d：处理用户选择

yes - 将建议的更改应用到该部分，然后继续下一部分

skip - 保持原内容不变，然后继续下一部分

modify - 用户提供反馈：

> modify: Keep the explanation but move it to a collapsible "Why?" block

### Revised Proposal

> ## Setting Up
>
> <details>
> <summary>Why this architecture?</summary>
>
> The system uses a microservices pattern because...
>
> </details>
>
> ### Steps
> [same as before]

**Your choice:** [yes / skip / modify]

步骤 3：处理混合类型的部分

对于归类为“Mixed”的部分：

---

## Section 5 of 5: "Configuration Options" (Mixed)

### Current Content

> ## Configuration Options
>
> Let's walk through configuring your application. First, you'll need
> to understand the available options:
>
> | Option | Type | Default | Description |
> |--------|------|---------|-------------|
> | port | number | 3000 | Server port |
> | debug | boolean | false | Enable debug mode |
>
> Now let's configure each one step by step...

### Issues Found

1. **Mixed types**: Tutorial framing ("Let's walk through") with Reference content (options table)

### Recommendation

Split into two sections:

1. **Reference section** - "Configuration Reference" with the options table
2. **Tutorial section** - "Configuring Your First App" with learning-oriented walkthrough

Would you like me to:
1. **Split** - Create both sections
2. **Reference only** - Keep just the table, remove tutorial framing
3. **Tutorial only** - Expand into full tutorial, move table to appendix

步骤 4：写入更新后的文档

处理完所有部分后：

1. 根据已接受的更改构建更新后的内容
2. 原样保留未更改的部分
3. 用更新后的内容覆盖原始文件

步骤 5：报告结果

## Refinement Complete

**File:** `docs/guides/getting-started.md`

### Changes Summary

| Section | Action | Type |
|---------|--------|------|
| Setting Up | Improved | How-To |
| Configuration Options | Split | Reference + Tutorial |
| Authentication | Improved | How-To |
| Why We Built This | Skipped | Explanation |

### Sections Modified

- **Setting Up**: Removed tangent, split steps, added verification
- **Configuration Options**: Split into "Configuration Reference" and "Configuring Your App"
- **Authentication**: Added prerequisites, made steps atomic

### New Sections Created

- **Configuration Reference** (Reference): Options table from split
- **Configuring Your App** (Tutorial): Learning walkthrough from split

### Recommendations

Consider creating these additional documents:
- `docs/explanation/architecture-overview.md` - For content removed from "Setting Up"

The original file has been updated.

规则

• 在阶段转换及保存到 Path 之前，遵循 Gates 的要求
• 分析前始终加载 docs-style 技能
• 遇到部分时再按需加载特定类型的技能
• 优化阶段完成前，绝不修改文件（参见 Gates：overwrite）
• 将标记为“skip”的部分原样保留
• 拆分部分时，保持逻辑上的阅读顺序
• 类型分类不明确时（置信度 < 70%），提出澄清问题
• 对于“Mixed”部分，始终将拆分作为首选方案
• 指出问题时，提供具体的行号引用
• 在有帮助时，以 diff 格式展示提议的更改
• 尊重用户的“modify”反馈——持续迭代，直到用户回复“yes”或“skip”
• 如果进行了重大重组，在输出中添加备份说明