doc-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# `/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).

---

## 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):**

```powershell
$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):**

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

From ffroliva/gflow-cli, MIT.

More from ffroliva/gflow-cli