doc-quality-review

What this skill does

# 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

| Resource | Purpose | Load when |
|----------|---------|-----------|
| `references/personas.md` | Six concrete reader personas with quality signals | Always (Phase 1) |
| `references/quality-dimensions.md` | Doc-type-aware scoring rubrics for each dimension | Always (Phase 1) |
| `references/style-checklist.md` | Concrete style rules for common issues | Phase 2 (review pass) |

---

## 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:

```yaml
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 au