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.

Every CLI surface in that list has an MCP twin — grade both. docs/MCP.md and the mcp/tools.py docstrings are documentation for an agent audience, and they rot the same way, silently, with a green test suite. Two failure shapes, both release-blocking:

• Absent: a CLI flag shipped and mirrored in code, but docs/MCP.md never mentions the MCP parameter. The D0–D4 grading above applies unchanged.
• False: the tool docstring or docs/MCP.md still asserts a restriction the code dropped. This is worse than absent — it tells agents not to attempt something that now works, and no link check, lint, or parity test can see it. Grade a false claim as a blocker regardless of how well-documented the surface otherwise is.

# Cross-check every behavioural claim about models/flags in the MCP surface against the code.
grep -rn "rejected\|not supported\|requires a\|only\|coming soon" src/gflow_cli/mcp/tools.py docs/MCP.md

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