enhance-docs

# enhance-docs

Analyze documentation for readability, structure, and RAG optimization.

## Parse Arguments

```javascript
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:**
```markdown
# 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:**
```markdown
# 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

```markdown
## 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>
```markdown
## Installation
[2000+ tokens of mixed content covering install, config, and usage]
```
</bad_example>
<good_example>
```markdown
## Installation
[400 tokens - installation only]

## Configuration
[300 tokens - config only]

## Usage
[400 tokens - usage only]
```
</good_example>

### Position-Aware Content
<bad_example>
```markdown
## Introduction
[Long background...]

## History
[More context...]

## Critical Setup Steps
[Important info buried in middle]
```
</bad_example>
<good_example>
```markdown
## 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>
```markdown
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>
```markdown
| 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