doc-review

/gflow:doc-review — Documentation Review Gate

Run this gate before cutting a release. Two phases:

1. Mechanical checks (sections 1–7 below) — fast, scripted, deterministic. Run inline.
2. LLM council audit (section 8) — 3 parallel review subagents, then consensus synthesis. The mechanical pass catches stale strings and dead links; the council catches drift between docs, fictional claims, and gaps a human reader would notice.

Every item reports PASS / UPDATED / WARN / FAIL. Any FAIL or any RED council verdict blocks the release.

Provenance: the council protocol below was validated on the v0.8.1 docs refresh release (2026-05-23). The audit found 11 fixable issues that the mechanical checklist alone missed (e.g., the experimental/ subpackage fiction in 3 files, the gflow video i2v non-working hero snippet in README). Keep the council step — it pays for itself.

0 · Pre-flight

• Confirm you are on the release branch (release/vX.Y.Z or hotfix/...), not on develop or main.
• If a release spec exists at docs/superpowers/specs/YYYY-MM-DD-*-design.md, identify it now — the council auditors will use it as the ground truth for "what was supposed to ship."
• If there is no spec, that is also fine — the council will work from the docs alone, but flag the absence as a process risk.

1 · Version references

Check these files for stale version strings (old numbers, outdated status labels):

Quick grep:

grep -rn "v[0-9]\+\.[0-9]" README.md AGENTS.md llms.txt CLAUDE.md PLAN.md KNOWN_ISSUES.md CHANGELOG.md pyproject.toml docs/PROJECT_STATUS.md

Historical references in CHANGELOG.md, docs/LIVE_VERIFICATION_v*.md, and milestone-history rows in docs/PROJECT_STATUS.md are allowed.

2 · docs/INDEX.md completeness

Every .md in docs/ needs an entry; every entry must point to a real file. AGENTS.md and llms.txt also need rows since they are agent-facing entry points.

# Files in docs/ missing from INDEX.md
for f in docs/*.md; do
  grep -q "$(basename "$f")" docs/INDEX.md || echo "MISSING from INDEX: $f"
done

# Entries in INDEX.md pointing to deleted files
grep -o 'docs/[^)]*\.md' docs/INDEX.md | while read path; do
  [ -f "$path" ] || echo "DEAD LINK in INDEX: $path"
done

# AGENTS.md, llms.txt rows present?
grep -E "AGENTS\.md|llms\.txt" docs/INDEX.md || echo "MISSING: agent-facing root files row"

3 · Per-release evidence file

After each release a docs/LIVE_VERIFICATION_vX.Y.Z.md must exist.

• Latest version has one (create stub if live run already documented elsewhere).
• docs/INDEX.md "latest release" cue points to it.
• Previous versions' files are preserved (historical record — never delete).
• File contains both a Pre-tag gates section (filled before signing) and a Post-tag evidence section (filled after publish).

4 · Doc-link validation

Run the link checker:

$env:PYTHONUTF8=1
uv run python scripts/ci/check_doc_links.py

Expected: All links resolved across N files. (exit 0). Broken links must be fixed in source docs before continuing — do not edit the script to ignore them.

If scripts/ci/check_doc_links.py is absent, create it from the v0.8.1 plan (it is a 30-line stdlib-only Python script).

4b · Published website (website/) — part of the documentation work, not a follow-up

website/ is the mkdocs-material site published to GitHub Pages, and website/docs/ is an anonymized copy of canonical docs/. Treat updating it as part of the same change that touched the docs: a documentation uplift is not done until the published surface reflects it. The mirror has drifted silently for months before (PR #362 shipped a PII leak; content lagged canonical for whole releases), which is why all three gates below exist.

1. PII gate (the CI check — a leak fails the build):

$env:PYTHONUTF8=1
uv run python scripts/ci/check_website_docs_pii.py

Expected: No private identifiers found across N published website/docs files.

2. Content-drift + nav check — the mirror is generated from canonical by scripts/ci/generate_website_docs.py (the anonymization map is data in that script). Verify it is in sync (this is the same check CI runs):

$env:PYTHONUTF8=1
uv run python scripts/ci/generate_website_docs.py --check

Expected: website/docs mirror in sync (N files), nav complete.

• Any DRIFT: line is a FAIL — a canonical doc changed and the mirror was not regenerated. Fix it:

  uv run python scripts/ci/generate_website_docs.py   # regenerate, then stage website/docs/
  

• Any NAV-ORPHAN: line is a FAIL — the page is published but no nav: entry in website/mkdocs.yml points at it, so it exists on the site only for whoever guesses the URL. Mirroring a doc and wiring it into the nav are two separate acts; add the entry under the right nav section and re-run.

3. New canonical doc → decide explicitly whether it is published. Not every doc belongs on the site (release evidence, recon specs, and plans generally do not). If it should be published: create the file under website/docs/, add its nav: entry in website/mkdocs.yml, and the generator maintains the content thereafter. If it should not, say so in the review so the omission is a decision rather than an oversight.

CHANGELOG.md and the bespoke site pages (index.md, agents.md, installation.md, onboarding*.md) are intentionally NOT generated — the generator's WEBSITE_ONLY set excludes them.

4c · Code↔docs parity (git-driven — the highest-value lens)

The mechanical checks and the council's drift auditor read from the docs outward ("does this doc claim match the code?"). They do NOT reliably catch the inverse — shipped work that no doc mentions at all — because no string sweep notices an absent doc. This lens (adapted from the auditing-documentation skill's dimension 3) reads from the code outward.

# Everything that shipped since the last release tag (or origin/develop on a feature branch).
git log --oneline "$(git describe --tags --abbrev=0)"..HEAD
git diff --stat "$(git describe --tags --abbrev=0)"..HEAD

For each shipped surface — new CLI flags/env vars, new modules under src/gflow_cli/, new operational behavior — name the doc that covers it, and assign a coverage grade: D0 (nothing) · D1 (docstrings only) · D2 (one line in INDEX/README) · D3 (dedicated how-to-operate doc) · D4 (D3

• troubleshooting + linked from an entrypoint). Anything operator-facing must be D3+; a new env var or command at D0/D1 is a release-blocking finding. List every surface below D3 with its grade and the doc it needs.

5 · Skill files (skills/ + .claude/commands/gflow/)

Canonical skill CONTENT lives in skills/<name>/SKILL.md; .claude/commands/gflow/ holds thin wrappers. Scan BOTH for stale phase/version references:

Scan all skills for stale phase/version references:

grep -rn "v[0-9]\+\.[0-9]\|Phase [A-Z0-9]" skills/ .claude/commands/gflow/

Also confirm the process skills stay in step with infra changes — e.g. when a new CI gate or published surface lands (scripts/ci/*, the website/docs/ mirror), the skills that should run it (check, doc-review, release) name it.

Update in the release prep commit if any references are wrong. The release.md skill's step list and the plan.md skill's phase pointers age fastest.

6 · CHANGELOG link footer

tail -10 CHANGELOG.md

Must read: [Unreleased]: …compare/vNEW_VERSION…HEAD and each prior [X.Y.Z]: …compare/vPREV…vCURR.

7 · Memory files

Check C:\Users\ffrol\.claude\projects\C--development-github-gflow-cli\memory\:

cd "C:\Users\ffrol\.claude\projects\C--development-github-gflow-cli\memory"
grep -o '\[.*\]([^)]*\.md)' MEMORY.md | grep -o '([^)]*)' | tr -d '()' | while read f; do
  [ -f "$f" ] || echo "DEAD LINK: $f"
done

8 · LLM council audit (NEW — required for every release ≥ v0.8.1)

The mechanical checks above catch stale strings, dead links, and missing files. They do not catch:

• A doc claiming a subpackage exists when it does not (no string sweep would notice).
• Two docs covering the same topic with subtly different facts.
• A working-looking hero snippet that points to a stub command (gflow video i2v returned "not yet available" but appeared as a production loop above the fold in v0.8.1).
• A user-facing onboarding gap that a fresh reader would hit immediately.

The council does. Dispatch three review subagents in parallel (they are read-only and independent). Each writes its verdict to tmp/council/.

Setup

mkdir -p tmp/council

Auditor 1 — Completeness

Role: as a fresh user / fresh AI agent, what do you need that isn't there?

Audit:

• README.md, AGENTS.md, llms.txt, CLAUDE.md, docs/INDEX.md, docs/PROJECT_STATUS.md
• docs/ARCHITECTURE.md (especially any new sections)
• docs/LIVE_VERIFICATION_v*.md (latest)
• CHANGELOG.md (just the new entry)
• pyproject.toml
• The release spec at docs/superpowers/specs/ (if present)
• The implementation plan at docs/superpowers/plans/ (if present)

Output to tmp/council/01-completeness.md with verdict GREEN / YELLOW / RED and four sections:

1. Critical gaps (block release)
2. Important gaps (fix before next release)
3. Nice-to-haves (track for next version)
4. What's done well (preserve)

Auditor 2 — Cross-reference & alignment

Role: do the docs agree with each other? Where two files cover the same topic, do they say the same thing?

Check:

• Install instructions, auth flow, headed-browser story, version number, Python requirement — all match exactly?
• Internal [X](path) links — files exist AND claims at the link target equivalent to the linking-doc's claim?
• Routing chain (README → AGENTS.md → CLAUDE.md → docs/INDEX.md) — consistent? Any contradictions?
• CHANGELOG vs PROJECT_STATUS — milestone history matches changelog entries?
• Spec vs implementation — does the shipped state match the design spec?

Output to tmp/council/02-crossref.md with verdict + four sections (inconsistencies / drift / broken anchors / well-aligned).

Auditor 3 — Drift & staleness

Role: does the documentation match the actual code and project state? Where are claims unverifiable, contradicted by reality, or referencing things that no longer exist?

Check empirically (every claim needs ls / grep / cat evidence cited inline):

• Version claims — pyproject.toml, __init__.py, every "v0.8.1 — alpha" statement agree?
• Module / file claims — every src/gflow_cli/{...} module list verified against the actual source tree?
• Subpackage claims (e.g., experimental/) — do those directories exist?
• CLI command claims in hero snippets — is the subcommand really implemented? Does it actually do what the example shows, or is it a stub?
• Exit-code claims — verify the range against errors.py::EXIT_CODE_MAP.
• Skill files, GIF assets, slash-command files — exist at the paths claimed?

Output to tmp/council/03-drift.md with verdict + three sections (fictional claims / stale references / verified-real).

Consensus

After all three reports return:

1. Read all three. List every distinct finding.
2. Tier the findings:
   • Tier 1 (release-blocking) — any RED verdict, any "block release" finding, any fictional claim that ships to PyPI.
   • Tier 2 (important polish) — drift between related docs, minor mismatches, missing-but-recoverable references.
   • Tier 3 (track for later) — nice-to-haves, prose improvements, deferred features.
3. Apply Tier 1 fixes immediately (block the release until done).
4. Apply Tier 2 fixes if the release schedule permits, otherwise open issues.
5. Tier 3 → backlog (memory phase-X-followups.md or a new GitHub issue).

Synthesize a single fix-plan comment under the relevant LIVE_VERIFICATION_vX.Y.Z.md Pre-tag gates entry for /gflow:doc-review:

Council verdict: <GREEN|YELLOW|RED> across all 3 auditors. findings; Tier 1 fixed in commit , Tier 2 fixed in commit , Tier 3 deferred to backlog. Council reports at tmp/council/0{1,2,3}-*.md (local-only).

If any auditor returns RED, stop and escalate to the user. Do not apply fixes blindly to a RED finding — it usually means the doc is wrong about the code, the code is wrong about the doc, or both.

Output format

After each section write one line:

[0] Pre-flight        — PASS (release spec at docs/superpowers/specs/YYYY-MM-DD-*.md)
[1] Version refs      — PASS
[2] INDEX completeness — UPDATED (added AGENTS.md row)
[3] Evidence file     — PASS
[4] Doc-link check    — PASS (9 files, 0 broken)
[5] Skill files       — UPDATED (refreshed /gflow:plan phase pointer)
[6] CHANGELOG footer  — PASS
[7] Memory files      — WARN: phase-b-followups.md has shipped items not yet ticked
[8] Council audit     — YELLOW (11 findings, all fixed in commit abc1234)

Then list every UPDATED change, every WARN / FAIL finding, and the council fix list for the user to review.

Integration with /gflow:release

This skill is invoked at step 9 of /gflow:release (between "review commands for staleness" and "commit the release prep"). The mechanical pass (sections 1–7) is the same as before; the council audit (section 8) is the new requirement and runs after the mechanical pass succeeds.

All discovered fixes are folded into the release prep commit unless genuinely unrelated to the release.

Post-release: memory consolidation

After the release ships and the back-merge completes, the release spec and implementation plan under docs/superpowers/{specs,plans}/ are project-management artifacts, not user-facing docs. The durable knowledge they contain (patterns learned, governance rules, architecture decisions) should be extracted into project memory at ~/.claude/projects/<...>/memory/, then the spec/plan files deleted from the repo in a final cleanup commit.

This keeps the public-facing docs/ tree focused on what users and contributors need, while the planning artifacts live on as memory entries usable by future Claude Code sessions. See the release-back-merge-gap-recovery memory and the v0.8.1 release commit history for an example.