name: document-release version: 1.0.0 description: | Post-ship documentation update. Reads all project docs, cross-references the diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when asked to "update the docs", "sync documentation", or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. allowed-tools:
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
mkdir -p ~/.gstack/sessions
touch ~/.gstack/sessions/"$PPID"
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
echo "PROACTIVE: $_PROACTIVE"
_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true)
_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
echo "TELEMETRY: ${_TEL:-off}"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
mkdir -p ~/.gstack/analytics
echo '{"skill":"document-release","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
for _PF in ~/.gstack/analytics/.pending-*; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done
If PROACTIVE is "false", do not proactively suggest gstack skills — only invoke
them when the user explicitly asks. The user opted out of proactive suggestions.
If output shows UPGRADE_AVAILABLE <old> <new>: read ~/.claude/skills/gstack/gstack-upgrade/SKILL.md and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If JUST_UPGRADED <from> <to>: tell user "Running gstack v{to} (just updated!)" and continue.
If LAKE_INTRO is no: Before continuing, introduce the Completeness Principle.
Tell the user: "gstack follows the Boil the Lake principle — always do the complete
thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean"
Then offer to open the essay in their default browser:
open https://garryslist.org/posts/boil-the-ocean
touch ~/.gstack/.completeness-intro-seen
Only run open if the user says yes. Always run touch to mark as seen. This only happens once.
If TEL_PROMPTED is no AND LAKE_INTRO is yes: After the lake intro is handled,
ask the user about telemetry. Use AskUserQuestion:
Help gstack get better! Community mode shares usage data (which skills you use, how long they take, crash info) with a stable device ID so we can track trends and fix bugs faster. No code, file paths, or repo names are ever sent. Change anytime with
gstack-config set telemetry off.
Options:
If A: run ~/.claude/skills/gstack/bin/gstack-config set telemetry community
If B: ask a follow-up AskUserQuestion:
How about anonymous mode? We just learn that someone used gstack — no unique ID, no way to connect sessions. Just a counter that helps us know if anyone's out there.
Options:
If B→A: run ~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous
If B→B: run ~/.claude/skills/gstack/bin/gstack-config set telemetry off
Always run:
touch ~/.gstack/.telemetry-prompted
This only happens once. If TEL_PROMPTED is yes, skip this entirely.
ALWAYS follow this structure for every AskUserQuestion call:
_BRANCH value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
Per-skill instructions may add additional formatting rules on top of this baseline.
AI-assisted coding makes the marginal cost of completeness near-zero. When you present options:
| Task type | Human team | CC+gstack | Compression |
|---|---|---|---|
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
| Test writing | 1 day | 15 min | ~50x |
| Feature implementation | 1 week | 30 min | ~30x |
| Bug fix + regression test | 4 hours | 15 min | ~20x |
| Architecture / design | 2 days | 4 hours | ~5x |
| Research / exploration | 1 day | 3 hours | ~3x |
Anti-patterns — DON'T do this:
If _CONTRIB is true: you are in contributor mode. You're a gstack user who also helps make it better.
At the end of each major workflow step (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better!
Calibration — this is the bar: For example, $B js "await fetch(...)" used to fail with SyntaxError: await is only valid in async functions because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore.
NOT worth filing: user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs.
To file: write ~/.gstack/contributor-logs/{slug}.md with all sections below (do not truncate — include every section through the Date/Version footer):
# {Title}
Hey gstack team — ran into this while using /{skill-name}:
**What I was trying to do:** {what the user/agent was attempting}
**What happened instead:** {what actually happened}
**My rating:** {0-10} — {one sentence on why it wasn't a 10}
## Steps to reproduce
1. {step}
## Raw output
{paste the actual error or unexpected output here}
## What would make this a 10
{one sentence: what gstack should have done differently}
**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill}
Slug: lowercase, hyphens, max 60 chars (e.g. browse-js-no-await). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
When completing a skill workflow, report status using one of:
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
Bad work is worse than no work. You will not be penalized for escalating.
Escalation format:
STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]
After the skill workflow completes (success, error, or abort), log the telemetry event.
Determine the skill name from the name: field in this file's YAML frontmatter.
Determine the outcome from the workflow result (success if completed normally, error
if it failed, abort if the user interrupted).
PLAN MODE EXCEPTION — ALWAYS RUN: This command writes telemetry to
~/.gstack/analytics/ (user config directory, not project files). The skill
preamble already writes to the same directory — this is the same pattern.
Skipping this command loses session duration and outcome data.
Run this bash:
_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - _TEL_START ))
rm -f ~/.gstack/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
~/.claude/skills/gstack/bin/gstack-telemetry-log \
--skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \
--used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null &
Replace SKILL_NAME with the actual skill name from frontmatter, OUTCOME with
success/error/abort, and USED_BROWSE with true/false based on whether $B was used.
If you cannot determine the outcome, use "unknown". This runs in the background and
never blocks the user.
Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
Check if a PR already exists for this branch:
gh pr view --json baseRefName -q .baseRefName
If this succeeds, use the printed branch name as the base branch.
If no PR exists (command fails), detect the repo's default branch:
gh repo view --json defaultBranchRef -q .defaultBranchRef.name
If both commands fail, fall back to main.
Print the detected base branch name. In every subsequent git diff, git log,
git fetch, git merge, and gh pr create command, substitute the detected
branch name wherever the instructions say "the base branch."
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:
Never stop for:
NEVER do:
Write tool on CHANGELOG.md — always use Edit with exact old_string matchesCheck the current branch. If on the base branch, abort: "You're on the base branch. Run from a feature branch."
Gather context about what changed:
git diff <base>...HEAD --stat
git log <base>..HEAD --oneline
git diff <base>...HEAD --name-only
find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | sort
Classify the changes into categories relevant to documentation:
Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."
Read each documentation file and cross-reference it against the diff. Use these generic heuristics (adapt to whatever project you're in — these are not gstack-specific):
README.md:
ARCHITECTURE.md:
CONTRIBUTING.md — New contributor smoke test:
CLAUDE.md / project instructions:
Any other .md files:
For each file, classify needed updates as:
Make all clear, factual updates directly using the Edit tool.
For each file modified, output a one-line summary describing what specifically changed — not just "Updated README.md" but "README.md: added /new-skill to skills table, updated skill count from 9 to 10."
Never auto-update:
For each risky or questionable update identified in Step 2, use AskUserQuestion with:
RECOMMENDATION: Choose [X] because [one-line reason]Apply approved changes immediately after each answer.
CRITICAL — NEVER CLOBBER CHANGELOG ENTRIES.
This step polishes voice. It does NOT rewrite, replace, or regenerate CHANGELOG content.
A real incident occurred where an agent replaced existing CHANGELOG entries when it should have preserved them. This skill must NEVER do that.
Rules:
/ship from the
actual diff and commit history. It is the source of truth. You are polishing prose, not
rewriting history.old_string matches — never use Write to overwrite CHANGELOG.md.If CHANGELOG was not modified in this branch: skip this step.
If CHANGELOG was modified in this branch, review the entry for voice:
After auditing each file individually, do a cross-doc consistency pass:
This is a second pass that complements /ship's Step 5.5. Read review/TODOS-format.md (if
available) for the canonical TODO item format.
If TODOS.md does not exist, skip this step.
Completed items not yet marked: Cross-reference the diff against open TODO items. If a
TODO is clearly completed by the changes in this branch, move it to the Completed section
with **Completed:** vX.Y.Z.W (YYYY-MM-DD). Be conservative — only mark items with clear
evidence in the diff.
Items needing description updates: If a TODO references files or components that were significantly changed, its description may be stale. Use AskUserQuestion to confirm whether the TODO should be updated, completed, or left as-is.
New deferred work: Check the diff for TODO, FIXME, HACK, and XXX comments. For
each one that represents meaningful deferred work (not a trivial inline note), use
AskUserQuestion to ask whether it should be captured in TODOS.md.
CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.
If VERSION does not exist: Skip silently.
Check if VERSION was already modified on this branch:
git diff <base>...HEAD -- VERSION
If VERSION was NOT bumped: Use AskUserQuestion:
If VERSION was already bumped: Do NOT skip silently. Instead, check whether the bump still covers the full scope of changes on this branch:
a. Read the CHANGELOG entry for the current VERSION. What features does it describe?
b. Read the full diff (git diff <base>...HEAD --stat and git diff <base>...HEAD --name-only).
Are there significant changes (new features, new skills, new commands, major refactors)
that are NOT mentioned in the CHANGELOG entry for the current version?
c. If the CHANGELOG entry covers everything: Skip — output "VERSION: Already bumped to
vX.Y.Z, covers all changes."
d. If there are significant uncovered changes: Use AskUserQuestion explaining what the
current version covers vs what's new, and ask:
The key insight: a VERSION bump set for "feature A" should not silently absorb "feature B" if feature B is substantial enough to deserve its own version entry.
Empty check first: Run git status (never use -uall). If no documentation files were
modified by any previous step, output "All documentation is up to date." and exit without
committing.
Commit:
git add -A or git add .).git commit -m "$(cat <<'EOF'
docs: update project documentation for vX.Y.Z.W
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"
git push
PR body update (idempotent, race-safe):
gh pr view --json body -q .body > /tmp/gstack-pr-body-$$.md
If the tempfile already contains a ## Documentation section, replace that section with the
updated content. If it does not contain one, append a ## Documentation section at the end.
The Documentation section should include a doc diff preview — for each file modified, describe what specifically changed (e.g., "README.md: added /document-release to skills table, updated skill count from 9 to 10").
Write the updated body back:
gh pr edit --body-file /tmp/gstack-pr-body-$$.md
rm -f /tmp/gstack-pr-body-$$.md
gh pr view fails (no PR exists): skip with message "No PR found — skipping body update."gh pr edit fails: warn "Could not update PR body — documentation changes are in the
commit." and continue.Structured doc health summary (final output):
Output a scannable summary showing every documentation file's status:
Documentation health:
README.md [status] ([details])
ARCHITECTURE.md [status] ([details])
CONTRIBUTING.md [status] ([details])
CHANGELOG.md [status] ([details])
TODOS.md [status] ([details])
VERSION [status] ([details])
Where status is one of: