doc-review

name	doc-review
version	1.0
description	Use before cutting any gflow-cli release or after a major documentation change — systematic council-driven audit that combines a mechanical 7-section checklist with a 3-agent parallel review (completeness / cross-reference / drift). Produces a consensus verdict and a concrete fix list.

/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):

File	What to verify
README.md	Status badge, "Project status" section, install example
AGENTS.md	Module list, exit-code range, dev-environment commands
llms.txt	Header summary (Python version, stable surface claims)
CLAUDE.md	"Active phase" pointer if present
PLAN.md	Phase status (IN PROGRESS / DONE) and version annotations
KNOWN_ISSUES.md	Open entries resolved by this release → move to Resolved with evidence
CHANGELOG.md	[Unreleased] empty; link footer matches new version
pyproject.toml + src/gflow_cli/__init__.py	Both set to the new version
docs/PROJECT_STATUS.md	"Current release" subsection + milestone-history row for this version

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).

---

5 · .claude/commands/gflow/ skill files

Scan all skills for stale phase/version references:

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

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

File	What to verify
MEMORY.md	All listed files exist; no dangling entries
phase-b-followups.md	Items shipped in this release marked done
video-generation-spec.md	PR/status accurate
image-generation-401-next.md	Resolution status and evidence pointer still valid
release-signing.md	Procedure section matches what was actually done
release-back-merge-gap-recovery.md	Still relevant; gap from any prior release recorded

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.