enhance-docs

# enhance-docs

Analyze documentation for readability, structure, and RAG optimization.

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