# review-documentation (Unified Skill)

## Core Instructions (SKILL.md)

# Review Documentation Quality

Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture.

## Core Rules

- You are a reviewer, not a writer. Flag issues with locations; do not rewrite content.

## Procedure

Perform 5 iterative passes. Check for convergence after each pass starting with Pass 2: report new CRITICAL issues, total new issues, the change vs. the previous pass, and status (CONVERGED or CONTINUE). Converge when no new CRITICAL issues are found and the new-issue rate drops below 10% versus the previous pass. Stop early if converged.

### Pass 1: Diátaxis & Intent

Goal: does this topic have a single, clear intent? Checks: is it a Tutorial, How-to, Reference, or Explanation? Are there leaked intents (e.g., too much theory in a Tutorial)? Issue prefix: [INTENT-001].

### Pass 2: EPPO & Standalone Utility

Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Issue prefix: [EPPO-001].

### Pass 3: Cognitive Scannability (Info Mapping)

Goal: can the reader scan the page in under 10 seconds and find the key answer? Checks: are descriptive labels used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are tables and lists used for complex data? Issue prefix: [SCAN-001].

### Pass 4: Accuracy, "Whole Game" & Fail-States

Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? Issue prefix: [ACC-001].

### Pass 5: Excellence & AI-Readiness

Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Issue prefix: [EXCL-001].

## Final Report

- Total Issues by Severity (Critical, High, Medium, Low).
- Top 3 Findings.
- Verdict: Ready, Needs Revision, or Needs Rework.
- Rationale.

## Rules

- Reference exact locations (file, section, paragraph).
- Validate issues exist; do not flag "potential" issues without evidence.
- The canonical theory lives in `content/research-documentation-frameworks.md`; `references/ai-readiness-criteria.md` is an operational excerpt that links back to it.

## Related Skills

- `research-documentation` — architecture-level gaps.
- `implement-documentation` — fixing what the review finds.

---

## Reference: ai-readiness-criteria.md

# AI-Readiness Criteria (Pass 5)

Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer First) catches surface issues; these checks catch whether the page is actually consumable by an AI agent. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability").

## LLM-friendly structure

- Is there a concise TL;DR (1-2 sentences) at the top suitable for context-window injection?
- Is the page free of navigation chrome when exported (menus, footers, ads) so the body text is clean?
- Is prose minimalist and high-signal? Verbose docs cost more and retrieve worse.

## RAG-compatible chunking

- Does the page cover one well-defined topic so it chunks cleanly for retrieval?
- Are section headings stable and unique so a chunk can be addressed precisely?
- Is there redundant cross-page duplication that would pollute retrieval results?

## Semantic headers

- Are headers descriptive of content, not generic ("Overview", "Details")?
- Are headers unique across the site so a model can disambiguate?
- Is front matter present (title, description, version, category) for indexing?

## Dual-audience precision

- Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent.
- Are error conditions and their meanings explicit?
- Are capability boundaries stated (what the tool/API can and cannot do)?

## Schema and spec sync (reference pages)

- For API reference: is it generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)?
- For tool/agent docs: are MCP manifests and agent cards present with precise descriptions and JSON schemas for inputs/outputs?
- Are code examples complete and runnable? Agents execute what they read; partial snippets mislead.

## Site-level (flag only if the page is the canonical entry)

- Is a `llms.txt` present at the documentation root and does it reference this page where authoritative?
- Are canonical URLs set so a model retrieves the current stable version?

---