name: enhance-docs description: "Use when improving documentation structure, accuracy, and RAG readiness." version: 5.0.0 argument-hint: "[path] [--fix] [--ai]"

OpenCode Note: Invoke agents using @agent-name syntax. Available agents: task-discoverer, exploration-agent, planning-agent, implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent Example: @exploration-agent analyze the codebase

enhance-docs

Analyze documentation for readability, structure, and RAG optimization.

Parse Arguments

(JavaScript reference - not executable in OpenCode)

Documentation Locations

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:

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

4. RAG Optimization (MEDIUM - AI Mode)

Chunk size guidelines:

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: (JavaScript reference - not executable in OpenCode)

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

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

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