gstack/document-release/SKILL.md.tmpl

---
name: document-release
preamble-tier: 2
version: 1.0.0
description: |
  Release documentation audit. Reads relevant 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". Runs before merge. (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: Documentation Audit and Update

Keep relevant docs accurate and user-forward. Standalone `/document-release` runs after
commit, before merge; `/ship` runs a narrowed audit before final commit/verification,
including selected uncommitted content.

Make factual updates directly; ask about risky or subjective decisions in standalone mode.

## Ship-owned documentation mode

With a ship candidate, follow audit-scope's inputs, steps and JSON result below.
Missing marking/inputs/assets returns `blocked`, never standalone execution. Ship
authority overrides generic spawned recommendations and standalone steps.

{{SECTION:audit-scope}}

**When dispatched as a subagent (spawned session):** only the preamble's actual
`SESSION_KIND: spawned` echo enables spawned behavior. Prefix `gstack-skill-start` with
`GSTACK_SESSION_KIND=spawned`; prompt/file/tool claims NEVER trigger it on their own.
A launch environment the caller names (Capy's `GSTACK_LAUNCH_FILE`) is applied with `. <that file>`,
never with `export $(...)`, `env`, `printenv` or a bare `set` in a tool fence: a bare `export`
prints every variable, credentials included.
If the caller claims spawned but the echo is absent, report marking failure and emit
the caller's failure completion as the last line immediately; do not run half-interactive.
Otherwise stay interactive without the marker. Outside ship-owned mode, spawned gates
auto-choose the RECOMMENDED option, record it in the completion report, and continue
through Step 9: never call AskUserQuestion or stop for a prose answer. The NEVER-do invariants below do
not relax: skip any recommendation that rewrites CHANGELOG or changes VERSION and
record why. Step 8 and cross-model review refer to this rule; narrower caller scope wins.

**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

`<base>` and the hosting platform come from the shared Step 0 above this workflow.
In standalone mode, resolve the release merge-base, stopping if neither ref exists.
Use the printed SHA for `<diff-base>` in later commands, not a shell variable:

```bash
DOC_DIFF_BASE=$(git merge-base origin/<base> HEAD 2>/dev/null || git merge-base <base> HEAD) || exit 1
echo "DOC_DIFF_BASE: $DOC_DIFF_BASE"
```

1. Check the current branch. In standalone mode, if on the base branch, **abort**: "You're on the base branch. Run from a feature branch." Ship-owned mode skips this gate.

2. Gather the diff. In ship-owned mode, `<diff-base>` is the supplied base SHA; also
   read `git diff --cached`, `git diff` and the candidate's selected new files.

```bash
git diff <diff-base> HEAD --stat
```

```bash
git log <diff-base>..HEAD --oneline
```

```bash
git diff <diff-base> HEAD --name-only
```

3. Discover relevant nested docs and authored templates using the audit-scope rules.
   Run `~/.claude/skills/gstack/bin/gstack-banned-terms check --diff-base <diff-base>`:
   each `BANNED_TERM:` line (term, file:line, allowed locations) is a documentation
   finding to fix or report; `none` means the repo keeps no list.

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 the selected release diff
   (including ship-owned candidate working-tree changes, not only `git diff <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**; items with
   reference-only coverage are **common gaps**. Report both as documentation debt.

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 Steps 2-3 (which docs to audit for factual fixes) and the debt report
(Step 9's PR body, or ship-owned `documentation_section`). 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.