/improve-doc

name: improve-doc
description: Analyze and improve existing documentation using Diataxis principles
disable-model-invocation: true

Improve Doc

Analyze an existing markdown document, classify sections by Diataxis type, identify issues, and interactively refine each section.

Arguments

• **Path:** Path to the markdown document to improve (required)

Workflow Overview

Invoke the **improve-doc** skill with a document path, e.g. `improve-doc docs/guides/getting-started.md`.

The skill runs in two phases:

1. **Analysis Phase:** Parse document, classify sections, identify issues 2. **Refinement Phase:** Interactive loop to improve each section

Gates

Hard sequencing — advance only when the **pass condition** is met (artifact or explicit user input, not assumed).

**Before Phase 2 (refinement):**

1. **Read** — Full contents of the file at **Path** are loaded.

• **Pass:** Enumerated sections (from `#` / `##` / `###` headings) cover every heading in the file; titles match the source.

2. **Core skill** — [docs-style](../docs-style/SKILL.md) is loaded (or its path read) before classification.

• **Pass:** Analysis output reflects at least one concrete principle from that skill (name it or quote briefly).

3. **Handoff** — User saw an analysis summary (template in Step 5 or equivalent) and entered **`start`** to begin refinement, or **`abort`** to exit.

• **Pass:** If `abort`, no writes to **Path**. If `start`, proceed to Phase 2.

**Before overwriting the file (Phase 2, Step 4):**

1. **Choices** — Every section with open issues has a terminal outcome: applied **`yes`**, unchanged **`skip`**, or **`modify`** loop finished with **`yes`** or **`skip`**.

• **Pass:** No section left in a pending `modify` state unless the user aborted the whole session (then do not write).

2. **Skips** — Content for every **`skip`** matches the original section text (copy preserved, not paraphrased).

• **Pass:** Full block equality check against the initial read (line-for-line, including whitespace).

3. **Write** — Only after the above.

• **Pass:** Single save to **Path**; completion report notes backup or major restructure if applicable (Rules).

**Ambiguous Diataxis type** — If classification is uncertain, do not edit that section until the user answers the clarifying fork (Step 2b) or explicitly confirms your stated default.

Phase 1: Analysis

Step 1: Read Document

Read the target markdown file and parse into sections based on headings:

• Each `#`, `##`, `###` heading starts a new section
• Capture heading level, title, and content
• Preserve hierarchy for context

Step 2: Load Core Skill

Load [docs-style](../docs-style/SKILL.md) for core writing principles that apply to all documentation types.

Step 3: Classify Each Section

For each section, determine the Diataxis type using these indicators (for the full decision procedure and the two key distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md)):

| Type | Indicators | |------|------------| | **Tutorial** | "Let's", "we will", step-by-step learning, builds toward a project, minimal explanation of why | | **How-To** | "How to" title, task-focused steps, assumes prior knowledge, goal-oriented | | **Reference** | Parameter tables, type signatures, API specs, factual descriptions, no narrative | | **Explanation** | "Why", "because", history, trade-offs, alternatives, conceptual discussion |

**Classification rules:**

1. Check title first - "How to X" is always How-To, "Why X" is always Explanation 2. Look for structural patterns - tables with parameters/types suggest Reference 3. Analyze language - learning-oriented ("Let's learn") vs task-oriented ("To accomplish X") 4. Consider context - what comes before/after this section 5. Mark as "Mixed" if section blends types (this is an issue to fix)

Step 4: Identify Issues

For each section, check for issues based on its detected type:

**Tutorial issues:**

• Explains "why" instead of just guiding the learner
• Skips steps assuming prior knowledge
• No clear learning outcome
• Missing "you will build/learn" framing

**How-To issues:**

• Includes explanatory tangents
• Missing prerequisites
• Steps not atomic (multiple actions per step)
• No verification that goal was achieved

**Reference issues:**

• Missing parameter types or return values
• Narrative text instead of factual description
• Incomplete coverage of options/parameters
• No code examples

**Explanation issues:**

• Includes procedural steps
• Missing context for "why"
• No trade-offs or alternatives discussed
• Reads like reference material

**Cross-type issues (any section):**

• Mixed Diataxis types in single section
• Unclear who the audience is
• Missing or vague heading
• Wall of text without structure

Step 5: Present Analysis

Display analysis summary to user:

## 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.

Phase 2: Interactive Refinement

Step 1: Load Type-Specific Skills