document-release

name	document-release
description	Post-ship documentation update. Cross-references the diff, updates README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md to match what shipped. Polishes CHANGELOG voice, cleans up TODOs, optionally bumps VERSION. Triggers: "update docs", "sync documentation", "post-ship docs", "update the readme", "document what shipped". Proactively suggest after a PR is merged or code is shipped.
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]
when_to_use	Post-ship only. Use after code has shipped to sync README, CHANGELOG, ARCHITECTURE with the diff. Optional — triggers: "update docs", "sync documentation".
produces	null
consumes	["docs/superomni/releases/release-[branch]-[session]-[date].md"]
dispatch-agent	doc-writer

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

/document-release — Post-Ship Documentation Update

Goal: After shipping, ensure all documentation matches what was actually built. Catch stale READMEs, outdated architecture docs, and missing CHANGELOG entries.

Iron Law: Never Mark Docs Done Without Diff Cross-Reference

Always read the actual diff before updating docs. Docs written from memory drift from reality.

Phase 1: Gather What Shipped

# What changed since last release/tag
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~20")..HEAD 2>/dev/null | head -30
git diff $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~20")..HEAD --stat 2>/dev/null | tail -20

# Or last N commits
git log --oneline -20

Build a mental model of what actually shipped:

• New features added
• APIs changed (added, removed, modified)
• Configuration changes
• Dependencies added/removed
• Breaking changes

Phase 2: Audit Existing Docs

Find all documentation files:

find . -name "README.md" -o -name "CHANGELOG.md" -o -name "ARCHITECTURE.md" \
       -o -name "CONTRIBUTING.md" -o -name "CLAUDE.md" -o -name "AGENTS.md" \
       -o -name "docs/*.md" 2>/dev/null | grep -v node_modules | grep -v .git

Dispatch the doc-writer agent with:

• The diff summary from Phase 1 (what shipped)
• The list of documentation files found
• Any existing README.md / ARCHITECTURE.md content (so the agent can match voice/style)
• Explicit instructions on which doc type needs updating: README / CHANGELOG / ARCHITECTURE / CONTRIBUTING

The agent returns a DOC WRITER REPORT with files written/updated. Incorporate its output and review each changed file for accuracy before committing.

For each doc, check:

• Does it reflect what shipped?
• Are installation instructions current?
• Are API examples accurate?
• Are feature lists complete?
• Are any sections obviously stale?

Phase 3: Update README

Check the README for:

1. Feature list — add new features, remove removed ones
2. Installation — verify all install commands still work
3. Usage examples — update for any API changes
4. Configuration — new config options documented?
5. Quick start — still accurate end-to-end?

Edit directly: do not add "Updated on [date]" noise.

Phase 4: Update CHANGELOG

Scaffold the entry from Conventional Commits using npm run gen:changelog -- --version <X.Y.Z>, then complete the Why this matters / Verified / Deferred subsections manually.

If a CHANGELOG exists, add an entry for the current version:

## [VERSION] — YYYY-MM-DD

### Added
- [Feature] — [one-line description]

### Changed
- [What changed] — [why]

### Fixed
- [Bug fixed] — [impact]

### Removed
- [What was removed] — [migration path if breaking]

Voice guidelines:

• Past tense ("Added X", not "Adds X")
• Lead with the user value, not the technical change
• Breaking changes get their own callout: ⚠️ BREAKING:

Phase 5: Update Architecture/Design Docs

If ARCHITECTURE.md, DESIGN.md, or docs/ exist:

1. Update component/module descriptions for anything that changed
2. Update data flow diagrams if data flows changed
3. Flag sections that are now stale but need more research to update

Phase 6: Clean Up TODOs

# Find all TODOs in docs
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.md" . | grep -v node_modules | grep -v .git

For each TODO:

• If the thing was shipped → remove the TODO
• If still valid → leave it
• If no longer relevant → remove it

Phase 7: VERSION Bump (Optional)

Ask the user if they want to bump the version:

# Check current version
cat package.json 2>/dev/null | grep '"version"' | head -1
cat VERSION 2>/dev/null

If yes, bump according to what shipped:

• New features, backward compatible → MINOR
• Bug fixes only → PATCH
• Breaking changes → MAJOR

Output Format

DOCUMENT RELEASE COMPLETE
════════════════════════════════════════
Files updated:   [N]
  ✓ README.md       [summary of changes]
  ✓ CHANGELOG.md    [entry added for vX.Y.Z]
  ✓ [other files]
TODOs cleared:   [N]
VERSION:         [old] → [new] (or: unchanged)

Status: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════════════════════════════