Doc Quality Review

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 audience read and understand this?

What to check:

• Sentence length — flag sentences over 30 words
• Paragraph length — flag paragraphs over 6 sentences
• Passive voice density — flag sections where >40% of sentences are passive
• Jargon — flag technical terms used without definition on first occurrence
• Ambiguous pronouns — "it", "this", "that" without clear referent
• Nominalizations — "perform an installation" instead of "install"

Dimension 2: Consistency

Does this doc use the same terms, formatting, and conventions throughout — and match the rest of the doc set?

What to check:

• Term alignment — same concept should use the same word everywhere
• Heading hierarchy — consistent use of ## vs ###, capitalization style
• Code block formatting — language tags present, consistent indentation
• List formatting — bullet vs number, punctuation, capitalization
• Admonition/callout style — consistent use of note/warning/tip conventions
• Tense — consistent within a doc type (imperative for instructions, present for descriptions)

Dimension 3: Audience Fit

Is the content calibrated to the right level for its intended readers?

What to check:

• Prerequisite assumptions — what must the reader already know?
• Explanation depth — does it match the audience's expected background?
• Context gaps — would a new reader understand why, not just what?
• Leaps — does the doc jump from basic to advanced without transition?
• Condescension — does it over-explain things the audience already knows?

Dimension 4: Structure & Scannability

Can a reader find what they need without reading linearly?

What to check:

• Heading hierarchy — does it create a useful outline?
• Front-loading — are key facts early in each section, or buried at the end?
• Tables vs prose — is reference data in tables or hidden in paragraphs?
• Section length — flag sections over 500 words without a subheading
• TL;DR — do long docs have a summary or overview section?

Dimension 5: Actionability

Can the reader do something after reading? (Weighted differently by doc type.)

What to check:

• Code examples — do they work if copy-pasted? Are imports included?
• Commands — are they complete with required flags and paths?
• Steps — are they sequential and numbered? Any missing steps?
• Expected output — does the doc show what success looks like?
• Error guidance — if something goes wrong, does the doc say what to do?

Dimension Weighting by Doc Type

---

Phase 3: Synthesize Findings (orchestrator-side)

After Phase 2's per-docfile sonnet calls return, the orchestrator aggregates results across the doc set. Synthesis stays orchestrator-side because it needs the full result set — no individual agent has that view. Look for patterns:

• Systemic issues — same problem across many docs (e.g., inconsistent terminology everywhere)
• Outliers — one doc much better or worse than the rest
• Audience mismatches — docs in the wrong section for their actual audience
• Style drift — sections written at different times with different conventions

Systemic issues are more valuable to fix than individual ones — fixing the pattern fixes many docs at once.

---

Phase 4: Produce the Quality Review

Report Format

# Documentation Quality Review

**Review date:** YYYY-MM-DD
**Scope:** [files or sections reviewed]
**Personas evaluated:** [comma-separated list]
**Doc types in scope:** [reference, tutorial, guide, explanation, ADR, runbook, README]

---

## Personas

[Inline the Phase 1 persona blocks — full profile per persona]

---

## Summary

[2-3 sentences: overall quality assessment with explicit persona context]

Per-persona aggregate scores (averaged across in-scope docs of each
type, weighted per the doc-type weighting table):

| Persona | Readability | Consistency | Audience Fit | Structure | Actionability | Weighted Total |
|---------|-------------|-------------|--------------|-----------|---------------|----------------|
| <persona A> | N/5 | N/5 | N/5 | N/5 | N/5 | N/25 |
| <persona B> | N/5 | N/5 | N/5 | N/5 | N/5 | N/25 |

Quality grade per persona: [A (22-25) / B (18-21) / C (14-17) / D (10-13) / F (<10)]

When grades differ between personas, that's a finding — surface in the
"Persona Conflicts" section below. Don't average away the divergence.

---

## Findings

### Critical (must fix before publish)

| # | File | Dimension | Issue | Fix |
|---|------|-----------|-------|-----|
| 1 | [path:line] | [dimension] | [specific problem] | [specific fix] |

### Major (should fix)

| # | File | Dimension | Issue | Fix |
|---|------|-----------|-------|-----|

### Minor (nice to fix)

| # | File | Dimension | Issue | Suggestion |
|---|------|-----------|-------|------------|

---

## Systemic Issues

### [Issue pattern name]
**Affected docs:** [list]
**Dimension:** [which]
**Pattern:** [what's happening across docs]
**Recommended fix:** [one-time fix that addresses all instances]

---

## Persona Conflicts

[For docs serving multiple personas where scoring diverges significantly.
Each entry identifies which persona the current structure favors and what
the cost is for the other persona(s).]

| Doc | Favors | At cost of | Recommendation |
|-----|--------|------------|----------------|
| [path] | [persona] | [other persona] | [split / restructure / accept bias intentionally] |

---

## Per-Document Scores

| Document | Persona | Read. | Cons. | Aud. | Struct. | Action. | Weighted Total |
|----------|---------|-------|-------|------|---------|---------|----------------|
| [path] | [persona A] | N | N | N | N | N | N |
| [path] | [persona B] | N | N | N | N | N | N |

---

## Strengths

[What's working well — cite specific examples worth emulating]

---

Integration with Other Doc Skills

doc-maintenance         →  Structural health (links, orphans, folders)
doc-claim-validator     →  Semantic accuracy (do claims match code?)
doc-completeness-audit  →  Topic coverage (is everything documented?)
doc-quality-review      →  Prose quality (is it well-written?)
doc-architecture-review →  Information architecture (is it findable?)

---

Anti-Patterns

• Do not rewrite docs during the review — produce findings, not rewrites
• Do not score without reading the full document — skimming misses context
• Do not apply tutorial standards to reference docs or vice versa — use the weighting table
• Do not penalize technical precision as "jargon" in docs for technical audiences
• Do not flag style preferences as quality issues — "I'd phrase it differently" is not a finding
• Do not review generated API docs (JSDoc, Sphinx auto) — review the source comments instead
• Do not score docs in docs/archive/ — they are historical

---

Bundled Resources

References

• references/quality-dimensions.md — Detailed scoring rubrics with examples for each score level
• references/style-checklist.md — Concrete style rules for the most common quality issues

Personas Library

Concrete reader profiles for evaluating documentation quality. Use these — don't invent fuzzier ones — when a sub-agent needs to score a doc against specific reader needs.

A "readable" or "well-structured" doc looks different for each persona below. Terse scannable prose works for the API Looker-Up but loses the Onboarding User; conversational explanation builds the Onboarding User's mental model but slows the Looker-Up. Apply the appropriate standard, not a generic one.

This file is shared with doc-architecture-review. When updating personas here, sync the change to that skill's references/personas.md to keep evaluation consistent across the doc-* family.

How to use this library

1. In Phase 1, identify the 1–3 personas that the doc serves primarily. Some docs serve only one persona (a runbook is for Incident Responder); others serve two or three (a CLI reference serves both API Looker-Up and Operator). 2. In agent prompts, inline the relevant personas verbatim. Don't summarize — sub-agents calibrate better with the explicit profile. 3. Score per-persona when audiences differ. A doc that scores 5/5 readability for Looker-Up may score 2/5 for Onboarding User. The higher score isn't "right" — both are real evaluations. 4. Surface persona mismatches as findings, not bugs. "Tutorial reads like reference — works for API Looker-Up, fails Onboarding User" is a real architectural finding.

Personas

Onboarding User

Quality signals — positive:

• Conversational tone that builds context
• Concepts introduced before use, with brief definition or analogy
• Generous examples — "this is what success looks like"
• Cross-links pointing forward to next stage of the journey
• Active voice, second person ("you do X")

Quality signals — negative:

• Reference-style terseness that assumes prior knowledge
• Jargon without definition
• Walls of code with no commentary
• Implicit prerequisites
• Passive constructions ("the system can be configured")

API Looker-Up

Quality signals — positive:

• Type signatures up-front (table format ideal)
• Terse, scannable prose
• Examples are minimal and focused on the one thing
• Edge cases enumerated
• Consistent template across pages — no relearning required

Quality signals — negative:

• Narrative explanation before the signature
• "See also" sections that bury the answer
• Paragraphs where a table would do
• Missing edge cases (null behavior, error returns)
• Inconsistent layout across reference pages

Incident Responder

Quality signals — positive:

• Imperative voice — "Run X. Verify Y. If Z, do W."
• Decision points clearly marked
• Copy-pasteable commands
• Rollback path stated up front
• Worst-case / most-common scenario first

Quality signals — negative:

• Hedging language ("you might want to consider…")
• Background / explanation before the procedure
• Steps that aren't actually steps ("understanding the system…")
• Missing rollback
• Cute prose ("Don't panic!" wastes time)

Architect Debugger

Quality signals — positive:

• Honest discussion of trade-offs ("we chose X over Y because…")
• Diagrams that match the code (citable file:line per box)
• Constraints documented, not just decisions
• Known limitations called out
• Links to related ADRs and conceptual docs

Quality signals — negative:

• Marketing prose without trade-off analysis
• Diagrams that don't match the current code
• Implementation detail without design rationale
• "Best practice" claims without context

Contributor

Quality signals — positive:

• All conventions in one place (CONTRIBUTING.md or linked from it)
• Working dev-setup commands
• Concrete examples of well-formed contributions
• Explicit ownership ("@team-X reviews changes to /server")

Quality signals — negative:

• Conventions scattered across many docs
• Dev setup that doesn't actually work
• Implicit rules surfaced only in PR review
• Outdated examples

Operator

Quality signals — positive:

• Every env var and config key documented (no "configure as needed")
• Concrete deployment recipes per platform
• Explicit upgrade paths between versions
• Monitoring / alerting recommendations
• Capacity guidance with real numbers

Quality signals — negative:

• "Configure as needed" without enumerating what's configurable
• Platform-specific instructions presented as platform-neutral
• Missing rollback guidance
• Vague capacity claims ("scales horizontally")

Doc type × default persona

When persona is unclear, the doc type strongly suggests one. Use these defaults if the doc itself doesn't make audience explicit, but always prefer evidence over assumption.

Multi-persona conflicts

A single doc legitimately serving multiple personas with different needs has structural tension. Surface as findings:

Persona conflicts that are intentional and well-managed (e.g., a README that explicitly handles both Onboarding and Casual evaluator with clear sections per audience) are not findings — note the intentional split as a strength.

Quality Dimensions — Doc-Type-Aware Scoring Rubrics

Detailed scoring criteria with examples per dimension and doc type. A "readable" doc looks different for a tutorial than for a reference; applying a single rubric to both produces systematic misjudgment.

Pair this file with references/personas.md. Each dimension specifies what 5/5 looks like for each doc type and which personas are most affected.

Doc types referenced below

---

Readability

Core question: Can the target persona read this without effort, given their context and time pressure?

Per-doc-type criteria

Reference — 5/5 looks like

authenticate(token: str, *, scope: str = "user") -> Session

Validates `token` and returns a Session. Raises InvalidTokenError if
the token is malformed or expired.

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| token | str  | (required) | JWT bearer token |
| scope | str  | "user"     | Access scope: "user", "admin", or "service" |

Examples:
    auth.authenticate(jwt_token)
    auth.authenticate(jwt_token, scope="admin")

Terse. Signature first. Table for parameters. Examples last. Reader finds what they need without reading prose.

Tutorial — 5/5 looks like

Now we'll create a Session for the current user. Sessions hold the
user's identity and access permissions, and most subsequent calls need
one.

Add this to `auth.py`:

session = auth.authenticate(token) print(f"Hello, {session.user.name}!")

If you see "Hello, <your name>!" — great, the token worked. If you see
`InvalidTokenError`, double-check the token in the previous step.

Conversational. Explains why, not just what. Shows expected output. Anticipates the failure mode.

Runbook — 5/5 looks like

## Auth service returning 503

**Symptom:** Auth API returns 503 for >1% of requests.

**Recovery:**
1. Check `/health` endpoint: `curl prod.auth/health`
2. If returns 200: secondary issue — check downstream (ratelimit, db).
3. If returns 5xx or hangs: restart auth pods.

kubectl rollout restart deploy/auth -n prod

4. Verify recovery: `/health` returns 200, error rate drops to <0.1%.

**Rollback:** None — restart is the recovery action.
**Escalation:** Page on-call DBA if error rate doesn't drop within 5min.

Imperative voice. Copy-pasteable. Decision points explicit. No prose about why the auth service might fail.

Common failure across types

Score levels

Universal readability flags (apply across types)

---

Consistency

Core question: Does this doc use the same terms, formatting, and conventions throughout — and match the rest of the doc set?

Per-doc-type criteria

Consistency is largely universal — the same concept should use the same word, the same admonition style, the same heading hierarchy across the doc set. But the templates differ by type:

Score levels

Examples (across types)

5/5: Every reference page uses the same Parameters table format. Every tutorial follows Goal → Prereqs → Steps → Verify. The term "skill" is used consistently — never "module" or "capability" for the same concept.

3/5: Some reference pages have a Parameters table, others use a bulleted list. Most tutorials follow the same shape but a few are structured differently. "config" and "configuration" both appear, used interchangeably.

1/5: Each reference page has a different layout. Tutorials are written by different authors at different times with different shapes. The same feature is called "hooks" in some docs and "automations" in others.

---

Audience Fit

Core question: Is the content calibrated for its intended persona?

Per-doc-type criteria

This dimension is by definition persona-dependent. The agent must score against the identified personas, not a generic standard.

Reference for API Looker-Up — 5/5

Assumes the reader knows what an API is, knows what they're looking for, and just wants the precise answer. No "what is authentication?" preamble. Type signatures are upfront. Edge cases enumerated.

Tutorial for Onboarding User — 5/5

States prerequisites explicitly. Introduces concepts before use. Builds mental model layer by layer. No "obviously…" or "as you know…" phrasing.

Runbook for Incident Responder — 5/5

Imperative. Steps are atomic. Decision points marked. Doesn't explain why the failure mode exists (link to a postmortem or design doc if the responder later wants context).

ADR for Architect Debugger — 5/5

Trade-offs explicit. Alternatives considered named. Constraints stated. Honest about limitations. The reader can reconstruct the reasoning.

Common audience misfits

Score levels

---

Structure & Scannability

Core question: Can the target persona find what they need without reading linearly?

Per-doc-type criteria

Scannability requirements differ sharply by persona time pressure.

Reference (Looker-Up) — 5/5

Tables for parameter listings. Each symbol on its own deep-linkable page. Front-loaded type signature. Examples below. No long prose sections.

Tutorial (Onboarding User) — 5/5

Linear is the expected shape. Headings name the goal of each step. Reader doesn't scan — they follow. But: clear "where am I" markers (Step 2 of 5). Each step ends with a verification.

Guide (Onboarding User or Operator) — 5/5

Goal at top. Prereqs visible. Numbered steps. Final "what's next" section. Code examples immediately follow the concept they illustrate.

Runbook (Incident Responder) — 5/5

Symptom heading matches alert text. Recovery steps numbered, copy- pasteable. Decision points marked. Critical info above the fold.

Explanation (Architect Debugger) — 5/5

Hierarchical headings build a mental outline. Trade-offs as named sub-sections. Diagrams placed near related prose. References at the bottom.

ADR — 5/5

Always 4 sections (Context / Decision / Consequences / Status). Status header at the top. Date and number visible.

README — 5/5

Above-the-fold: what it is, why use it, Quick Start link. Below: detailed sections, optional. Reader who scrolls only sees more depth, not different content.

Score levels

Common structure failures

---

Actionability

Core question: Can the persona do something after reading?

Per-doc-type criteria

Actionability matters very differently per type. Some docs aren't supposed to drive action.

Per-doc-type 5/5 examples

Tutorial / Guide — 5/5

1. Install with pip:

pip install cortex-cli

2. Verify the install:

cortex --version

   Expected output: `cortex 1.4.2` (or later).
3. If `cortex --version` says "command not found", check:
   - That `pip install` succeeded above
   - That your shell's `$PATH` includes pip's bin directory

Every step has a command. Expected output shown. Common failure mode addressed.

Runbook — 5/5

Same shape but with the urgency of an incident: minimal prose, imperative voice, decision points clear. (See Runbook example under Readability.)

Reference — 5/5

auth.refresh_token(token)

Returns: new_token (str)
Raises:  InvalidTokenError if `token` is expired by more than 24h
Example: new_token = auth.refresh_token(old_token)

Action is implicit — the reader copies the call shape into their code. Doesn't need step-by-step instructions; just needs the precise contract.

Explanation — 5/5

Cortex separates "skills" (knowledge packages) from "agents" (personas)
because the failure modes differ. A skill that's wrong gives every agent
that uses it the wrong knowledge; an agent that's wrong only affects work
done by that agent.

This separation has a cost: skills and agents must coordinate. We chose
this trade-off because…

Builds the mental model. The "action" is later — when the reader is designing skills or agents, they'll apply this understanding. Score actionability low here is correct, not a failure.

Score levels per doc type

---

Dimension weighting by doc type

The weights below reflect that some dimensions matter more for some doc types. Apply these weights when computing the weighted total.

Notes:

• Runbook weights actionability highest (1.6) — under incident pressure, structure and actionability dominate
• Explanation deprioritizes actionability (0.5) — building mental models is the goal
• ADR weights consistency high (1.2) — template adherence matters for an ADR set
• Reference weights structure high (1.3) — scannability is core to lookup

---

Universal flags (apply across types)

These flags are universal signals, but their weight differs by type and persona — see per-dimension scoring above.

Style Checklist

Concrete rules for the most common documentation quality issues. Use during Phase 2 to identify specific findings.

---

Prose

• [ ] Active voice. "Cortex discovers skills" not "Skills are discovered by Cortex"
• [ ] Imperative for instructions. "Run the command" not "You should run the command"
• [ ] Present tense for descriptions. "The CLI reads config from..." not "The CLI will read..."
• [ ] Concrete subjects. "The parser extracts..." not "It extracts..." (unless referent is obvious)
• [ ] No nominalizations. "Install" not "Perform an installation"
• [ ] No hedge stacking. "This might possibly help to potentially..." — pick one qualifier or none

Structure

• [ ] One topic per page. If a page covers two unrelated features, split it
• [ ] Front-load key info. The first sentence of a section should be its most important point
• [ ] Heading hierarchy. ## before ### before #### — no skipping levels
• [ ] Sentence case headings. "Getting started" not "Getting Started" (unless project convention differs)
• [ ] Parallel structure in lists. All items start with the same part of speech

Code Examples

• [ ] Language tag on every fenced block. `bash not `
• [ ] Copy-pasteable. Reader shouldn't need to edit the example to run it
• [ ] Show output for non-obvious commands. What does success look like?
• [ ] One concept per example. Don't combine three features in one code block
• [ ] No placeholder paths. Use realistic paths or explicit <placeholders> with explanation

Formatting

• [ ] Tables for reference data. If you're listing flags, options, or config keys, use a table
• [ ] Consistent admonitions. Use the project's callout convention (note/warning/tip), not bold text
• [ ] No orphan links. Every link should have context — why would the reader follow it?
• [ ] Consistent list markers. Bullets (-) for unordered, numbers for sequential steps

Terminology

• [ ] One term per concept. Don't alternate between synonyms ("config" / "configuration" / "settings")
• [ ] Define on first use. Technical terms get a brief definition or link the first time they appear
• [ ] Match the UI. If the product calls it "Skills", docs call it "Skills" — not "capabilities" or "modules"
• [ ] No internal jargon in user docs. "State file" vs ".active-agents file" — use what the user sees

Common Mistakes to Flag