doc-review · v1.0 · 2026-07-13 · sha256 09ceeddcdc55a295
doc-review v1.0A
Immutable. This exact content never changes and is served at /api/v1/blob/09ceeddcdc55a295.
---
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:
```bash
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.
```bash
# 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:
```powershell
$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:
```bash
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
```bash
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 |
```bash
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
```bash
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. <N> findings; <M> Tier 1 fixed in commit <SHA>, <K> Tier 2 fixed in commit <SHA2>, <J> 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.