Documentation Quality Review

Assess whether documentation is well-written, consistent, and appropriate for its audience. The output is a scored review with specific findings — not rewrites.

When to Use

• Before releases — ensure docs meet a quality bar
• During doc review — structured alternative to "looks good to me"
• When users report docs are confusing, inconsistent, or too technical
• After bulk doc generation — verify machine-written docs read naturally
• Periodic quality check on documentation health

Quick Reference

Workflow Overview

Phase 1: Scope       → Identify docs to review and their intended audience
Phase 2: Review      → Score each doc across quality dimensions
Phase 3: Synthesize  → Aggregate findings, identify patterns
Phase 4: Report      → Produce the scored quality review

Phase 1: Scope the Review (with persona discovery)

Before reviewing, establish context. Persona discovery is foundational — without it, scoring applies a generic standard that systematically misjudges docs whose audience differs from default. A reference doc that serves API Looker-Up reads as "too terse" against a generic readability rubric; against the right persona, that terseness is the goal.

1. Identify the docs — which files or sections are in scope?
2. Identify the doc type per file — reference, tutorial, guide, explanation, ADR, runbook, or README. (Use the type → default persona mapping in references/personas.md.)
3. Identify the personas — which 1–3 personas from references/personas.md are the primary readers per doc? When the doc type strongly suggests a persona, prefer that default unless the doc itself shows evidence of a different audience.
4. Note conflicts — when one doc legitimately serves multiple personas with different needs (e.g., a CLI reference serves both API Looker-Up and Operator), capture this. Per-persona scoring surfaces conflicts in the report.
5. Load the rubrics — references/quality-dimensions.md is now doc-type-aware. Each dimension has different 5/5 criteria per type.

Output of Phase 1

A scope manifest:

docs:
  - path: <path>
    type: reference | tutorial | guide | explanation | ADR | runbook | README
    primary_persona: <persona name from library>
    secondary_persona: <if applicable>
    conflict_notes: <if multiple personas with different needs>

This manifest feeds Phase 2's per-docfile sonnet dispatch.

Phase 2: Review Each Document (per-docfile sonnet dispatch)

Scoring 5 weighted dimensions across many docs strains an orchestrator's context window — reading 50+ docs sequentially blows up the budget and sequential scoring is slow. Dispatch one general-purpose + sonnet agent per docfile. Each agent receives:

• The full doc content
• The rubric from references/quality-dimensions.md
• The style checklist from references/style-checklist.md
• Audience and doc-type metadata established in Phase 1
• The dimension weighting table for the doc type

Each agent returns scores + specific findings for that one doc.

Dispatch parameters

subagent_type: "general-purpose"
model: "sonnet"
description: "Quality review for <docfile>"

Run dispatches in parallel batches of 4–8 (memory-aware) until all docs are scored. The orchestrator collects results and proceeds to Phase 3 synthesis.

Per-docfile prompt template

Score the document at <DOCFILE_PATH> across five quality dimensions,
calibrated to the persona(s) and doc type identified in Phase 1.

Doc metadata (from Phase 1 scope manifest):
- doc type: <reference | tutorial | guide | explanation | ADR | runbook | README>
- primary persona: <persona name>
- secondary persona: <if applicable>

Personas (verbatim from references/personas.md):
<INLINE FULL PERSONA PROFILE — do not summarize. Each profile is the
five-field structure plus the "evaluates positively / negatively"
lists. The agent calibrates against these signals.>

Doc-type-aware rubric (verbatim from references/quality-dimensions.md):
<INLINE the relevant per-doc-type criteria for each dimension. Specifically:
- The "5/5 looks like" example for this doc type
- The "common readability failure" / equivalent rows for this type
- The score table rows for this type>

Style checklist (from references/style-checklist.md):
<inline relevant style rules>

Dimension weighting for this doc type:
<INLINE the row from the weighting table>

Universal flags:
<INLINE the universal flag table>

Process:
1. Read the full document.
2. For each of the 5 dimensions, score against THIS doc type's rubric
   (not a generic standard). When the rubric says a dimension applies
   differently or N/A for this doc type, follow the rubric — do not
   apply a default.
3. Score per-persona when multiple personas are listed. Identify
   places where one persona scores high and another low; surface the
   conflict explicitly rather than averaging.
4. List specific findings per dimension with location, issue, fix.
5. Apply the weighting; report the weighted total per persona.

Output as YAML:

doc_path: <path>
doc_type: <...>
personas_evaluated: [<persona1>, <persona2>]
per_persona_scores:
  <persona1>:
    readability:    { raw: N, justification: "...", evidence: "verbatim quote with line ref" }
    consistency:    { raw: N, justification: "...", evidence: "..." }
    audience_fit:   { raw: N, justification: "...", evidence: "..." }
    structure:      { raw: N, justification: "...", evidence: "..." }
    actionability:  { raw: N, justification: "...", evidence: "..." }
    weighted_total: N
  <persona2>:
    ...
findings:
  - severity: critical | major | minor
    dimension: readability | consistency | audience_fit | structure | actionability
    affected_persona: <which persona this hurts most>
    location: "L42 or '## Section heading'"
    issue: "..."
    fix: "..."
persona_conflicts:
  - dimension: <which>
    description: "Doc favors <persona A> via <pattern>, costs <persona B> in <way>"
    recommendation: "<resolution: split doc, add structure for both, accept bias intentionally>"
strengths:
  - persona: <which>
    evidence: "<specific passage worth emulating for this persona>"

Critical: do NOT apply a generic 'good doc' standard. Apply the rubric
for THIS doc type and persona. A reference doc with no Quick Start is
correctly structured for its persona, not a deficiency. A runbook with
no background context is correctly structured under incident pressure,
not "missing explanation." Score against the rubric you were given.

Optimize for accuracy over volume. Cite specific lines or sections —
generic findings ("prose is dense") without location aren't actionable.

Why sonnet, not haiku

Quality scoring across 5 dimensions requires reading the full doc and holding the rubric + style rules + audience expectations in mind simultaneously. Haiku's excerpt reads + smaller context window strain on this combination. Sonnet handles the dimension juggling reliably; haiku tends to score by pattern-match (long sentences → low readability) without the calibration the rubric requires.

The cost trade-off: ~50 sonnet calls for a 50-doc set vs. one big haiku call. Per-docfile sonnet is cheaper than per-claim sonnet (where the count multiplies with claims) and produces substantially more reliable scores.

Scoring dimensions

Score each document across the five dimensions below. The agent prompt above inlines this table so the dispatched agent doesn't have to load the file.

Dimension 1: Readability

How easily can the target aud