diff --git a/CLAUDE.md b/CLAUDE.md index bc21f606..a2c10685 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -48,6 +48,7 @@ gstack/ ├── plan-ceo-review/ # /plan-ceo-review skill ├── plan-eng-review/ # /plan-eng-review skill ├── retro/ # Retrospective skill +├── document-release/ # /document-release skill (post-ship doc updates) ├── setup # One-time setup: build binary + symlink skills ├── SKILL.md # Generated from SKILL.md.tmpl (don't edit directly) ├── SKILL.md.tmpl # Template: edit this, run gen:skill-docs diff --git a/document-release/SKILL.md b/document-release/SKILL.md new file mode 100644 index 00000000..c6b9ad17 --- /dev/null +++ b/document-release/SKILL.md @@ -0,0 +1,429 @@ +--- +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. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +--- + + + +## Preamble (run first) + +```bash +_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) +``` + +If output shows `UPGRADE_AVAILABLE `: 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 `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. Context: project name, current branch, what we're working on (1-2 sentences) +2. The specific question or decision point +3. `RECOMMENDATION: Choose [X] because [one-line reason]` +4. Lettered options: `A) ... B) ... C) ...` + +If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. When you hit friction with **gstack itself** (not the user's app), file a field report. Think: "hey, I was trying to do X with gstack and it didn't work / was confusing / was annoying. Here's what happened." + +**gstack issues:** browse command fails/wrong output, snapshot missing elements, skill instructions unclear or misleading, binary crash/hang, unhelpful error message, any rough edge or annoyance — even minor stuff. +**NOT gstack issues:** user's app bugs, network errors to user's URL, auth failures on user's site. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with this structure: + +``` +# {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} +**How annoying (1-5):** {1=meh, 3=friction, 5=blocker} + +## Steps to reproduce +1. {step} + +## Raw output +(wrap any error messages or unexpected output in a markdown code block) + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-logs/{slug}.md` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). 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}" + +## Step 0: Detect base branch + +Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps. + +1. 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. + +2. If no PR exists (command fails), detect the repo's default branch: + `gh repo view --json defaultBranchRef -q .defaultBranchRef.name` + +3. 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." + +--- + +# 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 + +--- + +## 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 ...HEAD --stat +``` + +```bash +git log ..HEAD --oneline +``` + +```bash +git diff ...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 2: Per-File Documentation Audit + +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:** +- Does it describe all features and capabilities visible in the diff? +- Are install/setup instructions consistent with the changes? +- Are examples, demos, and usage descriptions still valid? +- Are troubleshooting steps still accurate? + +**ARCHITECTURE.md:** +- Do ASCII diagrams and component descriptions match the current code? +- Are design decisions and "why" explanations still accurate? +- Be conservative — only update things clearly contradicted by the diff. Architecture docs + describe things unlikely to change frequently. + +**CONTRIBUTING.md — New contributor smoke test:** +- Walk through the setup instructions as if you are a brand new contributor. +- Are the listed commands accurate? Would each step succeed? +- Do test tier descriptions match the current test infrastructure? +- Are workflow descriptions (dev setup, contributor mode, etc.) current? +- Flag anything that would fail or confuse a first-time contributor. + +**CLAUDE.md / project instructions:** +- Does the project structure section match the actual file tree? +- Are listed commands and scripts accurate? +- Do build/test instructions match what's in package.json (or equivalent)? + +**Any other .md files:** +- Read the file, determine its purpose and audience. +- Cross-reference against the diff to check if it contradicts anything the file says. + +For each file, classify needed updates as: + +- **Auto-update** — Factual corrections clearly warranted by the diff: adding an item to a + table, updating a file path, fixing a count, updating a project structure tree. +- **Ask user** — Narrative changes, section removal, security model changes, large rewrites + (more than ~10 lines in one section), ambiguous relevance, adding entirely new sections. + +--- + +## Step 3: Apply Auto-Updates + +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:** +- README introduction or project positioning +- ARCHITECTURE philosophy or design rationale +- Security model descriptions +- Do not remove entire sections from any document + +--- + +## Step 4: Ask About Risky/Questionable Changes + +For each risky or questionable update identified in Step 2, use AskUserQuestion with: +- Context: project name, branch, which doc file, what we're reviewing +- The specific documentation decision +- `RECOMMENDATION: Choose [X] because [one-line reason]` +- Options including C) Skip — leave as-is + +Apply approved changes immediately after each answer. + +--- + +## Step 5: CHANGELOG Voice Polish + +**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:** +1. Read the entire CHANGELOG.md first. Understand what is already there. +2. Only modify wording within existing entries. Never delete, reorder, or replace entries. +3. Never regenerate a CHANGELOG entry from scratch. The entry was written by `/ship` from the + actual diff and commit history. It is the source of truth. You are polishing prose, not + rewriting history. +4. If an entry looks wrong or incomplete, use AskUserQuestion — do NOT silently fix it. +5. Use Edit tool with exact `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: + +- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not, + rewrite the wording (not the content). +- Lead with what the user can now **do** — not implementation details. +- "You can now..." not "Refactored the..." +- Flag and rewrite any entry that reads like a commit message. +- Internal/contributor changes belong in a separate "### For contributors" subsection. +- Auto-fix minor voice adjustments. Use AskUserQuestion if a rewrite would alter meaning. + +--- + +## Step 6: Cross-Doc Consistency & Discoverability Check + +After auditing each file individually, do a cross-doc consistency pass: + +1. Does the README's feature/capability list match what CLAUDE.md (or project instructions) describes? +2. Does ARCHITECTURE's component list match CONTRIBUTING's project structure description? +3. Does CHANGELOG's latest version match the VERSION file? +4. **Discoverability:** Is every documentation file reachable from README.md or CLAUDE.md? If + ARCHITECTURE.md exists but neither README nor CLAUDE.md links to it, flag it. Every doc + should be discoverable from one of the two entry-point files. +5. Flag any contradictions between documents. Auto-fix clear factual inconsistencies (e.g., a + version mismatch). Use AskUserQuestion for narrative contradictions. + +--- + +## Step 7: TODOS.md Cleanup + +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. + +1. **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. + +2. **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. + +3. **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. + +--- + +## Step 8: VERSION Bump Question + +**CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.** + +1. **If VERSION does not exist:** Skip silently. + +2. Check if VERSION was already modified on this branch: + +```bash +git diff ...HEAD -- VERSION +``` + +3. **If VERSION was NOT bumped:** Use AskUserQuestion: + - RECOMMENDATION: Choose C (Skip) because docs-only changes rarely warrant a version bump + - A) Bump PATCH (X.Y.Z+1) — if doc changes ship alongside code changes + - B) Bump MINOR (X.Y+1.0) — if this is a significant standalone release + - C) Skip — no version bump needed + +4. **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 ...HEAD --stat` and `git diff ...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: + - RECOMMENDATION: Choose A because the new changes warrant their own version + - A) Bump to next patch (X.Y.Z+1) — give the new changes their own version + - B) Keep current version — add new changes to the existing CHANGELOG entry + - C) Skip — leave version as-is, handle later + + 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. + +--- + +## Step 9: Commit & Output + +**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:** + +1. Stage modified documentation files by name (never `git add -A` or `git add .`). +2. Create a single commit: + +```bash +git commit -m "$(cat <<'EOF' +docs: update project documentation for vX.Y.Z.W + +Co-Authored-By: Claude Opus 4.6 +EOF +)" +``` + +3. Push to the current branch: + +```bash +git push +``` + +**PR body update (idempotent, race-safe):** + +1. Read the existing PR body into a PID-unique tempfile: + +```bash +gh pr view --json body -q .body > /tmp/gstack-pr-body-$$.md +``` + +2. 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. + +3. 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"). + +4. Write the updated body back: + +```bash +gh pr edit --body-file /tmp/gstack-pr-body-$$.md +``` + +5. Clean up the tempfile: + +```bash +rm -f /tmp/gstack-pr-body-$$.md +``` + +6. If `gh pr view` fails (no PR exists): skip with message "No PR found — skipping body update." +7. If `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: +- Updated — with description of what changed +- Current — no changes needed +- Voice polished — wording adjusted +- Not bumped — user chose to skip +- Already bumped — version was set by /ship +- Skipped — file does not exist + +--- + +## 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. +- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person + who hasn't seen the code. diff --git a/document-release/SKILL.md.tmpl b/document-release/SKILL.md.tmpl new file mode 100644 index 00000000..e38c243c --- /dev/null +++ b/document-release/SKILL.md.tmpl @@ -0,0 +1,355 @@ +--- +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. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +--- + +{{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 + +--- + +## 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 ...HEAD --stat +``` + +```bash +git log ..HEAD --oneline +``` + +```bash +git diff ...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 2: Per-File Documentation Audit + +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:** +- Does it describe all features and capabilities visible in the diff? +- Are install/setup instructions consistent with the changes? +- Are examples, demos, and usage descriptions still valid? +- Are troubleshooting steps still accurate? + +**ARCHITECTURE.md:** +- Do ASCII diagrams and component descriptions match the current code? +- Are design decisions and "why" explanations still accurate? +- Be conservative — only update things clearly contradicted by the diff. Architecture docs + describe things unlikely to change frequently. + +**CONTRIBUTING.md — New contributor smoke test:** +- Walk through the setup instructions as if you are a brand new contributor. +- Are the listed commands accurate? Would each step succeed? +- Do test tier descriptions match the current test infrastructure? +- Are workflow descriptions (dev setup, contributor mode, etc.) current? +- Flag anything that would fail or confuse a first-time contributor. + +**CLAUDE.md / project instructions:** +- Does the project structure section match the actual file tree? +- Are listed commands and scripts accurate? +- Do build/test instructions match what's in package.json (or equivalent)? + +**Any other .md files:** +- Read the file, determine its purpose and audience. +- Cross-reference against the diff to check if it contradicts anything the file says. + +For each file, classify needed updates as: + +- **Auto-update** — Factual corrections clearly warranted by the diff: adding an item to a + table, updating a file path, fixing a count, updating a project structure tree. +- **Ask user** — Narrative changes, section removal, security model changes, large rewrites + (more than ~10 lines in one section), ambiguous relevance, adding entirely new sections. + +--- + +## Step 3: Apply Auto-Updates + +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:** +- README introduction or project positioning +- ARCHITECTURE philosophy or design rationale +- Security model descriptions +- Do not remove entire sections from any document + +--- + +## Step 4: Ask About Risky/Questionable Changes + +For each risky or questionable update identified in Step 2, use AskUserQuestion with: +- Context: project name, branch, which doc file, what we're reviewing +- The specific documentation decision +- `RECOMMENDATION: Choose [X] because [one-line reason]` +- Options including C) Skip — leave as-is + +Apply approved changes immediately after each answer. + +--- + +## Step 5: CHANGELOG Voice Polish + +**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:** +1. Read the entire CHANGELOG.md first. Understand what is already there. +2. Only modify wording within existing entries. Never delete, reorder, or replace entries. +3. Never regenerate a CHANGELOG entry from scratch. The entry was written by `/ship` from the + actual diff and commit history. It is the source of truth. You are polishing prose, not + rewriting history. +4. If an entry looks wrong or incomplete, use AskUserQuestion — do NOT silently fix it. +5. Use Edit tool with exact `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: + +- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not, + rewrite the wording (not the content). +- Lead with what the user can now **do** — not implementation details. +- "You can now..." not "Refactored the..." +- Flag and rewrite any entry that reads like a commit message. +- Internal/contributor changes belong in a separate "### For contributors" subsection. +- Auto-fix minor voice adjustments. Use AskUserQuestion if a rewrite would alter meaning. + +--- + +## Step 6: Cross-Doc Consistency & Discoverability Check + +After auditing each file individually, do a cross-doc consistency pass: + +1. Does the README's feature/capability list match what CLAUDE.md (or project instructions) describes? +2. Does ARCHITECTURE's component list match CONTRIBUTING's project structure description? +3. Does CHANGELOG's latest version match the VERSION file? +4. **Discoverability:** Is every documentation file reachable from README.md or CLAUDE.md? If + ARCHITECTURE.md exists but neither README nor CLAUDE.md links to it, flag it. Every doc + should be discoverable from one of the two entry-point files. +5. Flag any contradictions between documents. Auto-fix clear factual inconsistencies (e.g., a + version mismatch). Use AskUserQuestion for narrative contradictions. + +--- + +## Step 7: TODOS.md Cleanup + +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. + +1. **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. + +2. **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. + +3. **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. + +--- + +## Step 8: VERSION Bump Question + +**CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.** + +1. **If VERSION does not exist:** Skip silently. + +2. Check if VERSION was already modified on this branch: + +```bash +git diff ...HEAD -- VERSION +``` + +3. **If VERSION was NOT bumped:** Use AskUserQuestion: + - RECOMMENDATION: Choose C (Skip) because docs-only changes rarely warrant a version bump + - A) Bump PATCH (X.Y.Z+1) — if doc changes ship alongside code changes + - B) Bump MINOR (X.Y+1.0) — if this is a significant standalone release + - C) Skip — no version bump needed + +4. **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 ...HEAD --stat` and `git diff ...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: + - RECOMMENDATION: Choose A because the new changes warrant their own version + - A) Bump to next patch (X.Y.Z+1) — give the new changes their own version + - B) Keep current version — add new changes to the existing CHANGELOG entry + - C) Skip — leave version as-is, handle later + + 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. + +--- + +## Step 9: Commit & Output + +**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:** + +1. Stage modified documentation files by name (never `git add -A` or `git add .`). +2. Create a single commit: + +```bash +git commit -m "$(cat <<'EOF' +docs: update project documentation for vX.Y.Z.W + +Co-Authored-By: Claude Opus 4.6 +EOF +)" +``` + +3. Push to the current branch: + +```bash +git push +``` + +**PR body update (idempotent, race-safe):** + +1. Read the existing PR body into a PID-unique tempfile: + +```bash +gh pr view --json body -q .body > /tmp/gstack-pr-body-$$.md +``` + +2. 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. + +3. 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"). + +4. Write the updated body back: + +```bash +gh pr edit --body-file /tmp/gstack-pr-body-$$.md +``` + +5. Clean up the tempfile: + +```bash +rm -f /tmp/gstack-pr-body-$$.md +``` + +6. If `gh pr view` fails (no PR exists): skip with message "No PR found — skipping body update." +7. If `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: +- Updated — with description of what changed +- Current — no changes needed +- Voice polished — wording adjusted +- Not bumped — user chose to skip +- Already bumped — version was set by /ship +- Skipped — file does not exist + +--- + +## 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. +- **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person + who hasn't seen the code. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 9c81e968..84e4e5da 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -531,6 +531,7 @@ function findTemplates(): string[] { path.join(ROOT, 'plan-eng-review', 'SKILL.md.tmpl'), path.join(ROOT, 'retro', 'SKILL.md.tmpl'), path.join(ROOT, 'gstack-upgrade', 'SKILL.md.tmpl'), + path.join(ROOT, 'document-release', 'SKILL.md.tmpl'), ]; for (const p of candidates) { if (fs.existsSync(p)) templates.push(p); diff --git a/scripts/skill-check.ts b/scripts/skill-check.ts index 591a0c81..51a583a2 100644 --- a/scripts/skill-check.ts +++ b/scripts/skill-check.ts @@ -27,6 +27,8 @@ const SKILL_FILES = [ 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'setup-browser-cookies/SKILL.md', + 'gstack-upgrade/SKILL.md', + 'document-release/SKILL.md', ].filter(f => fs.existsSync(path.join(ROOT, f))); let hasErrors = false; diff --git a/test/skill-validation.test.ts b/test/skill-validation.test.ts index 2a947b15..e47a24a8 100644 --- a/test/skill-validation.test.ts +++ b/test/skill-validation.test.ts @@ -176,6 +176,7 @@ describe('Update check preamble', () => { 'ship/SKILL.md', 'review/SKILL.md', 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'retro/SKILL.md', + 'document-release/SKILL.md', ]; for (const skill of skillsWithUpdateCheck) { @@ -397,6 +398,7 @@ describe('No hardcoded branch names in SKILL templates', () => { 'qa/SKILL.md.tmpl', 'plan-ceo-review/SKILL.md.tmpl', 'retro/SKILL.md.tmpl', + 'document-release/SKILL.md.tmpl', ]; // Patterns that indicate hardcoded 'main' in git commands @@ -479,6 +481,7 @@ describe('v0.4.1 preamble features', () => { 'ship/SKILL.md', 'review/SKILL.md', 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'retro/SKILL.md', + 'document-release/SKILL.md', ]; for (const skill of skillsWithPreamble) {