// Use when improving documentation structure, accuracy, and RAG readiness.
Use when coordinating multiple enhancers for /enhance command. Runs analyzers in parallel and produces unified report.
Use when improving agent prompts, frontmatter, and tool restrictions.
Use when improving CLAUDE.md or AGENTS.md project memory files.
Use when checking cross-file consistency: tools vs frontmatter, agent references, duplicate rules, contradictions.
Use when reviewing hooks for safety, timeouts, and correct frontmatter.
Use when analyzing plugin structures, MCP tools, and plugin security patterns.
| name | enhance-docs |
| description | Use when improving documentation structure, accuracy, and RAG readiness. |
| version | 5.1.0 |
| argument-hint | [path] [--fix] [--ai] |
Analyze documentation for readability, structure, and RAG optimization.
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const aiMode = args.includes('--ai');
| 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 |
--ai)For agent-docs and RAG-optimized documentation:
--both, default)For user-facing documentation:
[text](#missing-anchor))Heading hierarchy:
Position-aware content (based on "lost in the middle" research):
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)
Token estimation: characters / 4 or words * 1.3
Unnecessary prose:
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.
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:
Context anchors:
# Bad - ambiguous start
## Configuration
It requires several settings...
# Good - self-contained
## Configuration
The plugin configuration requires several settings...
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.
| Issue | Fix |
|---|---|
| Inconsistent headings | H1 → H3 becomes H1 → H2 |
| Verbose phrases | Replace with concise alternatives |
| Missing code language | Add based on content detection |
## 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 |
| 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 | - | - |
<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>
<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>
<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>
agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - Token budgeting, position awareness, chunkingagent-docs/PROMPT-ENGINEERING-REFERENCE.md - Structure, information density