improve-doc

ドキュメントを改善する

既存の Markdown ドキュメントを分析し、セクションを Diataxis のタイプに分類して問題を特定し、各セクションを対話形式で改善します。

引数

• パス： 改善する Markdown ドキュメントへのパス（必須）

ワークフローの概要

ドキュメントのパスを指定して、improve-doc スキルを呼び出します。例：improve-doc docs/guides/getting-started.md。

このスキルは、次の 2 つのフェーズで実行されます。

1. 分析フェーズ： ドキュメントを解析し、セクションを分類して問題を特定します
2. 改善フェーズ： 各セクションを対話形式で改善します

ゲート

厳密な順序で進めます。合格条件（成果物または明示的なユーザー入力。推測は不可）を満たした場合にのみ次へ進みます。

フェーズ 2（改善）の前に：

1. 読み取り — パスで指定されたファイルの全内容が読み込まれていること。
   • 合格条件： 列挙したセクション（#／##／### の見出しを基準）がファイル内のすべての見出しを網羅し、タイトルが原文と一致していること。
2. コアスキル — 分類の前に docs-style が読み込まれている（または、そのパスが参照されている）こと。
   • 合格条件： 分析結果に、そのスキルの具体的な原則が少なくとも 1 つ反映されていること（原則名を挙げるか、短く引用します）。
3. 引き継ぎ — ユーザーが分析の概要（ステップ 5 のテンプレートまたは同等の内容）を確認し、改善を開始するために start と入力するか、終了するために abort と入力していること。
   • 合格条件： abort の場合、パスへの書き込みは行いません。start の場合、フェーズ 2 に進みます。

ファイルを上書きする前（フェーズ 2、ステップ 4）：

1. 選択 — 未解決の問題がある各セクションについて、最終的な結果が確定していること。適用する yes、変更せずに残す skip、または modify ループを yes か skip で終了する必要があります。
   • 合格条件： ユーザーがセッション全体を中断していない限り、保留中の modify 状態のセクションが残っていないこと（中断した場合は書き込みません）。
2. スキップ — skip を選択した各セクションの内容が、元のセクションのテキストと一致していること（言い換えずにコピーが保持されていること）。
   • 合格条件： 最初に読み込んだ内容とブロック全体が完全に一致していること（空白を含む、行単位の一致）。
3. 書き込み — 上記をすべて満たした後に限ります。
   • 合格条件： パスに対して 1 回だけ保存し、該当する場合はバックアップまたは大幅な再構成について完了報告に記載します（ルールを参照）。

Diataxis タイプが曖昧な場合 — 分類に確信が持てない場合は、ユーザーが確認の分岐（ステップ 2b）に回答するか、提示された既定の判断を明示的に承認するまで、そのセクションを編集しないでください。

フェーズ 1：分析

ステップ 1：ドキュメントを読む

対象の Markdown ファイルを読み込み、見出しに基づいてセクションに分割します。

• 各 #、##、### 見出しで新しいセクションを開始します
• 見出しレベル、タイトル、内容を取得します
• コンテキストを把握できるよう、階層を保持します

ステップ 2：コアスキルを読み込む

すべてのドキュメントタイプに適用されるコアライティング原則を確認するため、docs-style を読み込みます。

ステップ 3：各セクションを分類する

各セクションについて、次の指標を使用して Diataxis のタイプを判定します（詳細な判断手順と 2 つの重要な区別については、docs-style/references/diataxis-compass.md を参照してください）。

タイプ	指標
チュートリアル	「さあ」「これから行います」、段階的な学習、プロジェクトの完成を目指す、理由の説明は最小限
ハウツー	「方法」を示すタイトル、タスクに重点を置いた手順、事前知識を前提とする、目標志向
リファレンス	パラメーター表、型シグネチャー、API 仕様、事実に基づく説明、物語形式ではない
解説	「なぜ」、理由、歴史、トレードオフ、代替案、概念的な議論

分類ルール：

1. 最初にタイトルを確認します。「方法」を示すタイトルは常にハウツー、「理由」を示すタイトルは常に解説です
2. 構造上のパターンを確認します。パラメーターや型を含む表は、リファレンスを示唆します
3. 言葉遣いを分析します。学習志向（「学んでいきましょう」）か、タスク志向（「X を達成するには」）かを見極めます
4. コンテキストを考慮します。このセクションの前後に何があるかを確認します
5. セクションに複数のタイプが混在している場合は、「混合」と分類します（修正が必要な問題です）

ステップ 4：問題点を特定する

セクションごとに、検出されたタイプに基づいて問題点を確認します。

チュートリアルの問題点：

• 学習者を導くのではなく、「なぜ」を説明している
• 事前知識があることを前提として手順を省略している
• 明確な学習成果が示されていない
• 「何を作成／学習するか」という説明が不足している

ハウツーの問題点：

• 説明的な余談が含まれている
• 前提条件が不足している
• 手順が個別の作業に分かれていない（1 つの手順に複数の操作が含まれている）
• 目標を達成できたか確認できない

リファレンスの問題点：

• パラメーターの型または戻り値が不足している
• 事実に基づく説明ではなく、物語調の文章になっている
• オプション／パラメーターの説明が網羅されていない
• コード例がない

解説の問題点：

• 手順が含まれている
• 「なぜ」に関する背景説明が不足している
• トレードオフや代替案が説明されていない
• リファレンス資料のように読める

タイプ横断の問題点（すべてのセクション）：

• 1 つのセクションに複数の 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」のセクションでは、最初の選択肢として必ず分割を提案します
• 問題点を特定する際は、具体的な行番号を示します
• 有用な場合は、提案に差分形式の変更内容を表示します
• ユーザーの「modify」フィードバックを尊重し、「yes」または「skip」と言うまで修正を繰り返します
• 大幅な構成変更があった場合は、出力にバックアップの注記を作成します