agent-sh/enhance-docs

enhance-docs

Analyze documentation for readability, structure, and RAG optimization.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const aiMode = args.includes('--ai');

Documentation Locations

| Type | Location | Purpose | |------|----------|---------| | User docs | docs/*.md, README.md | Human-readable guides | | Agent docs | agent-docs/*.md | AI reference material | | Project memory | CLAUDE.md, AGENTS.md | AI context/instructions |

Optimization Modes

AI-Only Mode (--ai)

For agent-docs and RAG-optimized documentation:

• Aggressive token reduction
• Dense information packing
• Self-contained sections for retrieval
• Optimal chunking boundaries

Both Mode (--both, default)

For user-facing documentation:

• Balance readability with AI-friendliness
• Clear structure for both humans and retrievers

Workflow

1. Discover - Find all .md files
2. Parse - Extract structure and content
3. Check - Run pattern checks based on mode
4. Report - Generate markdown output
5. Fix - Apply auto-fixes if --fix

Detection Patterns

1. Link Validation (HIGH)

• Broken anchor links ([text](#missing-anchor))
• Links to non-existent files
• Malformed link syntax

2. Structure Validation (HIGH)

Heading hierarchy:

• No jumps (H1 → H3 without H2)
• Single H1 per document
• Code blocks with language tags

Position-aware content (based on "lost in the middle" research):

• Critical info at START or END of document
• Supporting details in MIDDLE
• Flag important content buried in middle sections

Recommended structure:

1. Overview/Purpose (START - high attention)
2. Quick Start / TL;DR
3. Detailed Content
4. Reference / API
5. Summary / Key Points (END - high attention)

3. Token Efficiency (HIGH - AI Mode)

Token estimation: characters / 4 or words * 1.3

Unnecessary prose:

• "In this document..."
• "As you can see..."
• "Let's explore..."
• "It's important to note that..."

Verbose phrases: | Verbose | Concise | |---------|---------| | "in order to" | "to" | | "due to the fact that" | "because" | | "has the ability to" | "can" | | "at this point in time" | "now" | | "for the purpose of" | "for" | | "in the event that" | "if" |

Target: ~1500 tokens for project memory files, flexible for reference docs.

4. RAG Optimization (MEDIUM - AI Mode)

Chunk size guidelines: | Size | Issue | |------|-------| | >1000 tokens | Too long, split into subtopics | | <50 tokens | Too short, merge with related content | | 200-500 tokens | Optimal for retrieval |

Semantic boundaries:

• Single topic per section
• Self-contained sections (avoid "It", "This" at section start)
• Clear section titles that describe content

Context anchors:

# Bad - ambiguous start
## Configuration
It requires several settings...

# Good - self-contained
## Configuration
The plugin configuration requires several settings...

5. Information Density (MEDIUM - AI Mode)

Prefer tables over prose:

# Bad - verbose
The function accepts a path parameter which is required,
a limit parameter which defaults to 10, and an optional
format parameter.

# Good - dense
| Param | Required | Default | Description |
|-------|----------|---------|-------------|
| path | Yes | - | File path |
| limit | No | 10 | Max results |
| format | No | json | Output format |

Prefer lists over paragraphs for sequential items.

Use code blocks for examples, commands, configurations.

6. Cross-Reference Quality (MEDIUM)

• Internal links should use relative paths
• External links should be stable (avoid commit hashes)
• Reference sections should point to canonical sources

7. Balance Suggestions (MEDIUM - Both Mode)

• Missing section headers in long content (>500 words without heading)
• Important information buried late in document
• Missing TL;DR or summary for long documents

Auto-Fixes

| Issue | Fix | |-------|-----| | Inconsistent headings | H1 → H3 becomes H1 → H2 | | Verbose phrases | Replace with concise alternatives | | Missing code language | Add based on content detection |

Output Format

## Documentation Analysis: {name}

**File**: {path}
**Mode**: {AI-only | Both}
**Tokens**: ~{count}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Link Issues
| Line | Issue | Fix | Certainty |

### Structure Issues
| Line | Issue | Fix | Certainty |

### Efficiency Issues [AI mode]
| Line | Issue | Fix | Certainty |

### RAG Issues [AI mode]
| Line | Issue | Fix | Certainty |

Pattern Statistics

| Category | Patterns | Mode | Certainty | |----------|----------|------|-----------| | Links | 3 | shared | HIGH | | Structure | 4 | shared | HIGH | | Token Efficiency | 3 | ai | HIGH | | RAG Optimization | 3 | ai | MEDIUM | | Information Density | 2 | ai | MEDIUM | | Cross-Reference | 2 | shared | MEDIUM | | Balance | 3 | both | MEDIUM | | Total | 20 | - | - |

<examples> ### Verbose Phrase <bad_example> ```markdown In order to configure the plugin, you need to... ``` </bad_example> <good_example> ```markdown To configure the plugin... ``` </good_example>

RAG Chunking

<bad_example>

## Installation
[2000+ tokens of mixed content covering install, config, and usage]

</bad_example> <good_example>

## Installation
[400 tokens - installation only]

## Configuration
[300 tokens - config only]

## Usage
[400 tokens - usage only]

</good_example>

Position-Aware Content

<bad_example>

## Introduction
[Long background...]

## History
[More context...]

## Critical Setup Steps
[Important info buried in middle]

</bad_example> <good_example>

## Quick Start (Critical)
[Important setup steps at START]

## Background
[Supporting context in middle]

## Reference
[Details...]

## Key Reminders
[Critical points repeated at END]

</good_example>

Tables vs Prose

<bad_example>

The API accepts three parameters. The first is `query` which is required.
The second is `limit` which defaults to 10. The third is `format`.

</bad_example> <good_example>

| Param | Required | Default |
|-------|----------|---------|
| query | Yes | - |
| limit | No | 10 |
| format | No | json |

</good_example> </examples>

References

• agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - Token budgeting, position awareness, chunking
• agent-docs/PROMPT-ENGINEERING-REFERENCE.md - Structure, information density

Constraints

• Auto-fix only HIGH certainty issues
• Preserve original tone and style
• Balance AI optimization with human readability (default mode)
• Don't remove content, only restructure or condense