46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
# Docs Guard — Review Checklist
|
|
|
|
Structured walk for review mode. Findings first, file:line evidence always. Priorities: false claims → drift → substance → navigation.
|
|
|
|
## Contents
|
|
|
|
- Pass 1: Claim verification
|
|
- Pass 2: Code samples
|
|
- Pass 3: Drift scan
|
|
- Pass 4: Substance
|
|
- Pass 5: Navigation
|
|
- Reporting
|
|
|
|
## Pass 1: Claim verification (must fix)
|
|
|
|
Run the full procedure in [verification.md](verification.md):
|
|
|
|
- Extract every symbol, flag, endpoint, config key, path, version, and behavioral claim.
|
|
- Verify each against its source of truth (definition site, parser, route table, changelog).
|
|
- Every unverified or contradicted claim is a Rule 1/3 finding with the contradicting file:line.
|
|
- Numbers and superlatives without a repo source are Rule 4 findings.
|
|
|
|
## Pass 2: Code samples (must fix)
|
|
|
|
For every fenced block, run the [code-samples.md](code-samples.md) checklist: imports, signatures, self-containment, local residue, secrets, shown output. Samples in docstrings count.
|
|
|
|
## Pass 3: Drift scan (should fix)
|
|
|
|
- Take the public API surface (or the diff, when reviewing a change) and grep the docs for renamed/removed symbols, old defaults, and dead flags.
|
|
- Check the changelog mentions what the docs claim is new, and versions agree (Rule 5).
|
|
- Cross-surface consistency: README vs reference vs docstrings vs config samples — one claim per fact, surfaces agreeing (Rule 6).
|
|
|
|
## Pass 4: Substance (should fix)
|
|
|
|
- Paraphrase docstrings, heading-restating sections, marketing adjectives, intro padding (Rule 7).
|
|
- Paraphrased upstream documentation that should be a link (Rule 8).
|
|
- Happy-path-only tutorials and API examples (Rule 9).
|
|
|
|
## Pass 5: Navigation (worth noting)
|
|
|
|
- TOC vs actual headings; internal links and anchors resolve; no TODO stubs or "coming soon" in published docs (Rule 10).
|
|
|
|
## Reporting
|
|
|
|
Use the SKILL.md reporting format (Claim / Reality / Fix). Lead with the count: "N claims checked, M false, K unverifiable." End with a verdict — publish / fix first / do not publish — and at most three things the docs do well. A review that verifies 40 claims and finds 2 false is a *good* result; say so.
|