From 503053638a16eaff0df384ecb85418764bb4f9b7 Mon Sep 17 00:00:00 2001
From: dan <dan@delpad>
Date: Wed, 31 Dec 2025 22:55:38 -0500
Subject: [PATCH] docs: update doc-review skill to match implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove Vale references (tool has own deterministic rules)
- Document all 12 deterministic + 7 LLM checks
- Add missing CLI flags (--llm, --format, --model)
- Add concrete example session with output

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 skills/doc-review/SKILL.md | 114 +++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 skills/doc-review/SKILL.md

diff --git a/skills/doc-review/SKILL.md b/skills/doc-review/SKILL.md
new file mode 100644
index 0000000..a80cd38
--- /dev/null
+++ b/skills/doc-review/SKILL.md
@@ -0,0 +1,114 @@
+---
+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
+```