mirror of https://github.com/garrytan/gstack.git
161 lines
6.5 KiB
Cheetah
161 lines
6.5 KiB
Cheetah
---
|
|
name: document-release
|
|
preamble-tier: 2
|
|
version: 1.0.0
|
|
description: |
|
|
Post-ship documentation update. Reads all project docs, cross-references the
|
|
diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation),
|
|
updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped,
|
|
detects architecture diagram drift, polishes CHANGELOG voice with a sell-test
|
|
rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation
|
|
debt in the PR body. Use when asked to "update the docs", "sync documentation",
|
|
or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack)
|
|
allowed-tools:
|
|
- Bash
|
|
- Read
|
|
- Write
|
|
- Edit
|
|
- Grep
|
|
- Glob
|
|
- AskUserQuestion
|
|
triggers:
|
|
- update docs after ship
|
|
- document what changed
|
|
- post-ship docs
|
|
---
|
|
|
|
{{PREAMBLE}}
|
|
|
|
{{BASE_BRANCH_DETECT}}
|
|
|
|
# Document Release: Post-Ship Documentation Update
|
|
|
|
You are running the `/document-release` workflow. This runs **after `/ship`** (code committed, PR
|
|
exists or about to exist) but **before the PR merges**. Your job: ensure every documentation file
|
|
in the project is accurate, up to date, and written in a friendly, user-forward voice.
|
|
|
|
You are mostly automated. Make obvious factual updates directly. Stop and ask only for risky or
|
|
subjective decisions.
|
|
|
|
**Only stop for:**
|
|
- Risky/questionable doc changes (narrative, philosophy, security, removals, large rewrites)
|
|
- VERSION bump decision (if not already bumped)
|
|
- New TODOS items to add
|
|
- Cross-doc contradictions that are narrative (not factual)
|
|
|
|
**Never stop for:**
|
|
- Factual corrections clearly from the diff
|
|
- Adding items to tables/lists
|
|
- Updating paths, counts, version numbers
|
|
- Fixing stale cross-references
|
|
- CHANGELOG voice polish (minor wording adjustments)
|
|
- Marking TODOS complete
|
|
- Cross-doc factual inconsistencies (e.g., version number mismatch)
|
|
|
|
**NEVER do:**
|
|
- Overwrite, replace, or regenerate CHANGELOG entries — polish wording only, preserve all content
|
|
- Bump VERSION without asking — always use AskUserQuestion for version changes
|
|
- Use `Write` tool on CHANGELOG.md — always use `Edit` with exact `old_string` matches
|
|
|
|
---
|
|
|
|
{{SECTION_INDEX:document-release}}
|
|
|
|
---
|
|
|
|
## Step 1: Pre-flight & Diff Analysis
|
|
|
|
1. Check the current branch. If on the base branch, **abort**: "You're on the base branch. Run from a feature branch."
|
|
|
|
2. Gather context about what changed:
|
|
|
|
```bash
|
|
git diff <base>...HEAD --stat
|
|
```
|
|
|
|
```bash
|
|
git log <base>..HEAD --oneline
|
|
```
|
|
|
|
```bash
|
|
git diff <base>...HEAD --name-only
|
|
```
|
|
|
|
3. Discover all documentation files in the repo:
|
|
|
|
```bash
|
|
find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | sort
|
|
```
|
|
|
|
4. Classify the changes into categories relevant to documentation:
|
|
- **New features** — new files, new commands, new skills, new capabilities
|
|
- **Changed behavior** — modified services, updated APIs, config changes
|
|
- **Removed functionality** — deleted files, removed commands
|
|
- **Infrastructure** — build system, test infrastructure, CI
|
|
|
|
5. Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
|
|
|
|
---
|
|
|
|
## Step 1.5: Coverage Map (Blast-Radius Analysis)
|
|
|
|
Before touching any documentation file, build a **coverage map** of what shipped vs what's
|
|
documented. This is inspired by the Diataxis framework (tutorial / how-to / reference / explanation)
|
|
— but applied as an audit lens, not a generation tool.
|
|
|
|
1. **Extract public surface changes from the diff.** Scan `git diff <base>...HEAD` for:
|
|
- New exported functions, classes, commands, CLI flags, config options, API endpoints
|
|
- New skills, workflows, or user-facing capabilities
|
|
- Renamed or removed public surface (modules, commands, features)
|
|
- New environment variables, feature flags, or configuration knobs
|
|
|
|
2. **For each new/changed public surface item, assess documentation coverage:**
|
|
|
|
```
|
|
Coverage map:
|
|
[entity] [reference?] [how-to?] [tutorial?] [explanation?]
|
|
/new-skill ✅ AGENTS.md ❌ ❌ ❌
|
|
--new-flag ✅ README ✅ README ❌ ❌
|
|
FooProcessor ❌ ❌ ❌ ❌
|
|
```
|
|
|
|
Use these definitions:
|
|
- **Reference** — factual description of what it is, its API, its options (README tables, AGENTS.md skill lists, API docs)
|
|
- **How-to** — task-oriented: "how to do X with this" (README examples, CONTRIBUTING workflows)
|
|
- **Tutorial** — learning-oriented: step-by-step walkthrough for newcomers (getting started guides)
|
|
- **Explanation** — understanding-oriented: "why this works this way" (ARCHITECTURE decisions, design rationale)
|
|
|
|
3. **Output the coverage map.** Items with zero coverage are **critical gaps** — flag them for
|
|
Step 3. Items with reference-only coverage are **common gaps** — note them for the PR body.
|
|
|
|
4. **Architecture diagram drift detection.** If ARCHITECTURE.md (or any doc) contains ASCII
|
|
diagrams or Mermaid blocks, extract entity names (modules, services, data flows) from the
|
|
diagrams. Cross-reference against the diff. Flag any diagram entities that were renamed,
|
|
split, removed, or moved in the code.
|
|
|
|
The coverage map feeds into Steps 2-3 (what to audit and fix) and Step 9 (documentation debt
|
|
summary in the PR body). Do NOT auto-generate missing documentation pages — flag gaps only.
|
|
When significant gaps are found, suggest running `/document-generate` to fill them.
|
|
|
|
---
|
|
|
|
{{SECTION:release-body}}
|
|
|
|
---
|
|
|
|
## Important Rules
|
|
|
|
- **Read before editing.** Always read the full content of a file before modifying it.
|
|
- **Never clobber CHANGELOG.** Polish wording only. Never delete, replace, or regenerate entries.
|
|
- **Never bump VERSION silently.** Always ask. Even if already bumped, check whether it covers the full scope of changes.
|
|
- **Be explicit about what changed.** Every edit gets a one-line summary.
|
|
- **Generic heuristics, not project-specific.** The audit checks work on any repo.
|
|
- **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md.
|
|
- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body
|
|
and future work. It does NOT auto-generate missing documentation pages or sections. When gaps
|
|
are found, suggest `/document-generate` as the follow-up skill.
|
|
- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not
|
|
auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly.
|
|
- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person
|
|
who hasn't seen the code.
|