document-release

Document Release: Post-Ship Documentation Update

<!-- Adapted from garrytan/gstack document-release (MIT). Attribution: README "Built on". -->

Announce at start: "I'm using the document-release skill to audit and update project documentation."

Run after code changes are committed but before PR merge. Ensures all project documentation accurately reflects shipped code.

Beads Integration

# Create a doc-update bead at start
bd create "Docs: update documentation for <branch>" -t chore

Closed with evidence at Step 9 — the single source of truth for the close command.

Key Operating Principles

Automation with guardrails: Make obvious factual corrections automatically (path updates, version numbers, table additions) but pause for subjective decisions (narrative changes, security model updates, large rewrites, version bumps).

Auto-update (apply without asking):

• Factual corrections derived directly from the diff
• Adding items to existing lists and tables
• Updating file paths, counts, and version numbers
• Fixing stale cross-references between documents
• Minor CHANGELOG wording polish (preserving all content)
• Marking TODOs as complete

Always ask before:

• Narrative or philosophy changes
• Removing any section
• Security model rewrites
• Large rewrites (10+ lines in one section)
• VERSION bumps
• New TODO items

Audit Methodology (9-Step Process)

Step 0: Platform Detection

Detect git platform (GitHub/GitLab/unknown) and determine the base branch. Use gh/glab if available, fall back to git-native commands.

Done when: the platform and base branch are both determined.

Step 1: Pre-flight and Diff Analysis

1. Verify you are on a feature branch (not base branch)
2. Gather what changed: git diff <base>..HEAD and git log --oneline <base>..HEAD
3. Discover all .md files: find . -name '.md' -not -path './.git/' -not -path './.worktrees/*'
4. Categorise changes: new features, behaviour changes, removals, infrastructure

Done when: the diff is gathered, all .md files are discovered, and every change is categorised.

Step 1.5: Coverage Map (Diataxis Blast-Radius Audit)

Catches missing docs (shipped public surface that was never documented) — the per-file audit (Step 2) only catches stale docs.

1. Extract new public surface from git diff <base>..HEAD. "Public surface" is whatever the project exposes to users — a general superset, not any one project type:
2. Apps: new API endpoints, CLI flags, config keys, env vars.
3. Libraries: new exported functions, classes, public types.
4. Tools / plugins: new skills, user-facing commands, hooks, manifest fields, install flags.
5. …plus any renamed or removed surface in the above.
6. Grid each item against the four Diataxis quadrants (definitions are generic; the doc targets in parentheses are examples, never a hardcoded file list):
7. Reference — factual descriptions, signatures, option lists (README tables, AGENTS.md lists)
8. How-to — task-oriented guidance (README examples, CONTRIBUTING workflows)
9. Tutorial — step-by-step learning paths (getting-started guides)
10. Explanation — rationale and design reasoning (ARCHITECTURE, design docs, ADRs)

``text <entity> reference how-to tutorial explanation <entity-1> yes no no no <entity-2> yes yes no no ``

1. Calibrate gaps (avoid alert-fatigue). The grid shows all four cells, but only judgment-confirmed gaps become debt: a new user-facing surface with zero coverage anywhere, OR missing the one quadrant that surface type genuinely needs (e.g. a new flag with no Reference; a new workflow with no How-to). Tutorial/Explanation are flagged only when the change is significant enough to warrant them. An empty cell the entity genuinely doesn't need is not a gap.
2. Guardrail — informs, never generates. The coverage map flags gaps for beads + the PR body; it does not auto-write doc pages. Point real gaps at the write-documentation skill as the follow-up.
3. Diagram-drift sub-check (flag-only). Scope to entity-bearing diagrams — architecture / component / data-flow diagrams whose labels name code entities (e.g. ARCHITECTURE.md, or docs/*.md Mermaid). Extract entity names, cross-reference the diff, and flag any the diff renamed or removed. Prose/workflow flowcharts (e.g. process dot graphs) are in scope only when a renamed skill/command/step is itself the label. Never auto-edit a diagram.
4. Empty-check gate (conservative early exit). After building the coverage map, if the diff is unambiguously doc-irrelevant — both (a) git diff <base>..HEAD --name-only -- '*.md' is empty (zero docs changed) and (b) the coverage map found no new user-facing surface — emit "All documentation is up to date" and exit without an empty commit. When in doubt, do not exit — run the full audit (Steps 2–9). A false-skip would ship undocumented surface (the failure this skill exists to prevent), which is strictly worse than a redundant audit.

Done when: every new public-surface item is grid-checked against the four quadrants, or the empty-check gate confirms the diff is doc-irrelevant.

Step 2: Per-File Documentation Audit

Read each documentation file and cross-reference against the diff:

| File | What to Check | |------|--------------| | README | Features, install steps, examples, troubleshooting still valid? | | Pinned Discussions post | Front-door claims (contribute/contact/links) still true? Body stays evergreen — no versions or counts. | | ARCHITECTURE | Diagrams, component descriptions, design rationale still accurate? | | CONTRIBUTING | Setup instructions work? Test tiers match reality? | | CLAUDE.md | Project structure tree, commands, build/test steps current? | | CHANGELOG | Entries present for all changes? Voice user-forward? | | Any other .md | Purpose clear, contradictions with diff? |

Classify each update as auto-update (factual, obvious) or ask-user (narrative, ambiguous, risky).

Done when: every documentation file is read and each needed update is classified auto-update or ask-user.

Step 3: Apply Auto-Updates

Make factual corrections directly. Each edit gets a specific one-line summary — not "updated README" but "README: added /new-skill to skills table, updated count 15 to 16".

Done when: every Step 2 auto-update is applied, each with a one-line summary.

Step 4: Ask About Risky Changes

Use your structured question tool for risky changes. Provide context, recommendation, and options.

Step 5: CHANGELOG Voice Polish

Critical rules:

• Never clobber entries — polish wording only, preserve all content
• Use Edit tool with exact string matches — never use Write to overwrite CHANGELOG.md
• Ensure each bullet leads with what the user can do, not implementation details
• Flag commit-message-style entries for rewrite to user-forward language
• Strip internal references — human-facing CHANGELOG/README entries do NOT carry ADR-NNNN or bd-xxxx tags. Those belong in commit messages and docs/decisions/ (gitignored, invisible to readers); in reader-facing prose they are noise pointing at nothing. Describe the change, not its tracking ID.

Sell-test (0–3 rubric). Score each entry — this scoring always applies:

• +1 What changed — names the specific feature/fix
• +1 Why care — user impact or pain removed
• +1 How to use — a command, flag, or link

Thresholds: <2 → rewrite the entry; 3 → gold (preserve as-is or minor wording only). Lead with what the user can now do ("You can now…"), not "Refactored…".

Optional contributor split (format-compatible). Only when a project keeps developer-only notes (migration steps, deprecation) in its CHANGELOG, move them to a clearly-separated sub-list — at a heading level/placement that respects the proje