Improve Doc

Analyze and improve existing documentation using Diataxis principles

Security Scan

The skill is an instruction-only doc-improvement helper that only reads and (with explicit user consent) writes the specified markdown file; its requirements and instructions align with its stated purpose.

Purpose & Capability

Name/description (improve markdown docs using Diataxis) match the instructions: read a provided markdown Path, classify sections, propose edits, and write back only after explicit user confirmation. It does not request unrelated binaries, credentials, or config paths.

Instruction Scope

SKILL.md instructs reading the target file and loading related doc-style skills, then running an analysis and an interactive refinement loop. All file reads/writes are scoped to the provided Path and the explicit gating rules require user input before any write. There are no instructions to read unrelated system files, environment variables, or to transmit data externally.

Install Mechanism

There is no install spec and no code files—this is instruction-only, so nothing is downloaded or written to disk by an installer. That is proportionate for the described purpose.

Credentials

The skill declares no required environment variables, credentials, or config paths. The instructions do reference loading other beagle-docs skills (e.g., beagle-docs:docs-style), which is reasonable for applying style rules but means those referenced skills should be trusted.

Persistence & Privilege

always is false (not force-included) and disable-model-invocation is true (the skill disallows model invocation). The skill only writes the target file after explicit user-driven gates (user must type 'start' and confirm per-section outcomes). It does not request permanent presence or modify other skills' configs.

Assessment

This skill appears coherent and limited to editing the markdown file you point it at. Before using it: (1) ensure you pass the intended file Path (it will read that file), (2) confirm the referenced helper skill (beagle-docs:docs-style) is trustworthy or available, (3) keep a backup or use version control since the skill will save a single overwrite only after you type 'start' and approve edits, and (4) review each proposed change in the interactive loop—the SKILL.md enforces explicit per-section consent before writing but you should still verify the edits before accepting them.

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

/beagle-docs:improve-doc docs/guides/getting-started.md

The command 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 — beagle-docs:docs-style 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 beagle-docs:docs-style 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:

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

As you encounter each section type, load the relevant skill if not already loaded:

• Tutorial sections: beagle-docs:tutorial-docs
• How-To sections: beagle-docs:howto-docs
• Reference sections: beagle-docs:reference-docs
• Explanation sections: beagle-docs:explanation-docs

Step 2: Refinement Loop

For each section with issues, in document order:

2a: Show Current State

---

## 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: Ask Clarifying Question (if needed)

If the type classification is uncertain:

### 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: Propose Improvement

### 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: Handle User Choice

yes - Apply the proposed changes to the section, continue to next

skip - Keep original content unchanged, continue to next

modify - User provides feedback:

> 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]

Step 3: Handle Mixed Sections

For sections classified as "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

Step 4: Write Updated Document

After all sections processed:

1. Build updated content from accepted changes
2. Preserve unchanged sections exactly as they were
3. Overwrite original file with updated content

Step 5: Report Results

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

Rules

• Follow Gates for phase transitions and before saving to Path
• Always load docs-style skill before analysis
• Load type-specific skills lazily as sections are encountered
• Never modify the file until refinement phase completes (see Gates: overwrite)
• Preserve sections marked "skip" exactly as-is
• When splitting sections, maintain logical reading order
• Ask clarifying questions when type classification is ambiguous (confidence < 70%)
• For "Mixed" sections, always offer split as the first option
• Include specific line references when identifying issues
• Show diff-style changes in proposals when helpful
• Respect user's "modify" feedback - iterate until they say "yes" or "skip"
• Create backup note in output if major restructuring occurred