---
name: doc-review
description: Lint markdown documentation for AI agent consumption using deterministic rules + LLM semantic checks
---

# doc-review - Documentation Quality for AI Agents

Evaluate documentation against rubrics optimized for AI "ingestibility" - making docs work well when consumed by LLMs and AI agents.

## When to Use

Invoke this skill when:
- Writing or updating AGENTS.md, CLAUDE.md, or similar agent-facing docs
- Before committing documentation changes
- To validate docs follow AI-friendly patterns
- Reviewing existing docs for clarity and structure

## Architecture

```
Stage 1: Deterministic Rules (fast, free)
├── 12 pattern-based checks
├── Runs instantly, no API cost
└── Catches ~40% of issues

Stage 2: LLM Semantic Checks (--llm flag)
├── 7 contextual detectors
├── Evaluates meaning, not just patterns
└── Only runs when explicitly requested
```

## Invocation

```bash
# Check a single file
doc-review README.md

# Check multiple files
doc-review docs/*.md

# Apply suggested fixes
doc-review --fix README.md

# Enable LLM semantic checks
doc-review --llm AGENTS.md

# Use specific model for LLM checks
doc-review --llm --model gpt-4o README.md

# Output as SARIF for CI integration
doc-review --format sarif docs/ > results.sarif

# Output as JSON for programmatic use
doc-review --format json README.md
```

## What It Checks

### Deterministic Rules (fast, free)

| Rule | What it catches |
|------|-----------------|
| code-lang | Code blocks without language tags |
| heading-hierarchy | Skipped heading levels (H2 → H4) |
| generic-headings | Vague headings ("Overview", "Introduction") |
| hedging-lang | Uncertain language ("might", "consider") |
| filler-words | Unnecessary verbosity |
| config-precision | Vague versions ("Python 3.x") |
| backward-refs | "As mentioned above" references |
| terminology | Inconsistent term usage |
| security-patterns | Hardcoded secrets, dangerous patterns |
| json-yaml-validation | Invalid JSON/YAML in code blocks |
| broken-table | Malformed markdown tables |
| unclosed-fence | Unclosed code fences |

### LLM Detectors (--llm flag)

| Detector | What it catches |
|----------|-----------------|
| contextual-independence | Sections that don't stand alone |
| prerequisite-gap | Missing setup/context |
| ambiguity | Unclear instructions |
| semantic-drift | Heading/content mismatch |
| negative-constraint | "Don't do X" without alternatives |
| state-conflict | Contradictory instructions |
| terminology-pollution | Inconsistent naming |

## Output Formats

- **text** (default): Human-readable with line numbers
- **json**: Structured output for programmatic use
- **sarif**: SARIF 2.1.0 for CI integration (GitHub, VS Code)

## Design Philosophy

doc-review optimizes for **recall over precision**. Findings are candidates for review, not errors:
- Agents verify cheaply - checking a flag costs seconds
- False negatives compound - missed issues persist
- Suppression is explicit - `<!-- doc-review: ignore rule-id -->` documents intent

## Example Session

```
$ doc-review CLAUDE.md

CLAUDE.md:45: [code-lang] Code block missing language tag
CLAUDE.md:89: [hedging-lang] Uncertain language: "you might want to"
CLAUDE.md:112: [backward-refs] Backward reference: "as mentioned above"

3 issues found (2 HIGH, 1 MED)

$ doc-review --fix CLAUDE.md
Applied 3 fixes to CLAUDE.md
```
