document-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"

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.

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)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"

如果输出显示

UPGRADE_AVAILABLE <旧版本> <新版本>

：请阅读

~/.claude/skills/gstack/gstack-upgrade/SKILL.md

并按照“内联升级流程”操作（如果已配置则自动升级，否则通过AskUserQuestion提供4个选项，若用户拒绝则记录暂不升级状态）。如果显示

JUST_UPGRADED <旧版本> <新版本>

：告知用户“正在运行gstack v{新版本}（刚完成更新！）”并继续后续操作。

AskUserQuestion Format

AskUserQuestion 格式要求

ALWAYS follow this structure for every AskUserQuestion call:

Re-ground: State the project, the current branch (use the
```
_BRANCH
```
value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.

Recommend:

RECOMMENDATION: Choose [X] because [one-line reason]

Options: Lettered options:
```
A) ... B) ... C) ...
```

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.

每次调用AskUserQuestion时必须遵循以下结构：

重新说明背景： 说明项目名称、当前分支（使用前置步骤输出的
```
_BRANCH
```
值——不要使用对话历史或gitStatus中的分支），以及当前的计划/任务。（1-2句话）
简化解释： 用通俗易懂的语言解释问题，确保聪明的16岁学生也能理解。不要使用原始函数名、内部术语或实现细节。使用具体例子和类比。说明功能，而非名称。

推荐选项：

RECOMMENDATION: 选择[X]，因为[一句话理由]

选项列表： 带字母的选项：
```
A) ... B) ... C) ...
```

假设用户已经20分钟没看这个窗口，也没有打开代码。如果你的解释需要阅读源代码才能理解，说明过于复杂。

针对特定技能的说明可能会在这个基础格式上添加额外的格式规则。

Contributor Mode

贡献者模式

_CONTRIB

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):

undefined

如果

_CONTRIB

的值为

true

：你处于贡献者模式。你是一名gstack用户，同时也参与工具的改进工作。

在每个主要工作流步骤结束时（不是每个命令之后），反思你使用的gstack工具。给你的体验打分（0-10分）。如果得分不是10分，思考原因。如果存在明显的、可操作的bug，或者gstack的代码或技能markdown有可以改进的地方——提交一份现场报告。也许我们的贡献者能帮助我们变得更好！

校准标准： 例如，

$B js "await fetch(...)"

曾经因为gstack没有将表达式包裹在异步上下文中而失败，报错

SyntaxError: await is only valid in async functions

。这是一个小问题，但输入是合理的，gstack本应处理——这种情况就值得提交报告。比这影响更小的问题可以忽略。

不值得提交的情况： 用户应用程序的bug、用户URL的网络错误、用户网站的认证失败、用户自己的JS逻辑bug。

提交报告： 写入

~/.gstack/contributor-logs/{slug}.md

，包含以下所有部分（不要截断——包括到日期/版本页脚的每个部分）：

undefined

{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}

嘿gstack团队——我在使用/{技能名称}时遇到了这个问题：

我尝试做的事情： {用户/agent试图完成的操作} 实际发生的情况： {实际出现的结果} 我的评分： {0-10} — {一句话说明为什么不是10分}

Steps to reproduce

复现步骤

{step}

{步骤}

Raw output

原始输出

{paste the actual error or unexpected output here}

{在此处粘贴实际错误或意外输出}

What would make this a 10

如何达到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}"

{一句话：gstack应该做出哪些不同的处理}

日期： {YYYY-MM-DD} | 版本： {gstack版本} | 技能： /{技能名称}


Slug：小写，用连字符连接，最多60个字符（例如`browse-js-no-await`）。如果文件已存在则跳过。每个会话最多提交3份报告。直接在当前流程中提交并继续——不要中断工作流。告知用户：“已提交gstack现场报告：{标题}”

Step 0: Detect base branch

步骤0：检测基础分支

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."

确定此PR的目标分支。将结果作为后续所有步骤中的“基础分支”。

检查此分支是否已存在PR：
```
gh pr view --json baseRefName -q .baseRefName
```
如果命令成功，使用输出的分支名称作为基础分支。
如果不存在PR（命令失败），检测仓库的默认分支：
```
gh repo view --json defaultBranchRef -q .defaultBranchRef.name
```
如果两个命令都失败，回退使用
```
main
```
分支。

输出检测到的基础分支名称。在后续所有

git diff

、

git log

、

git fetch

、

git merge

和

gh pr create

命令中，凡说明提到“基础分支”的地方，都替换为检测到的分支名称。

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

你正在运行

/document-release

工作流。此工作流在

/ship

（代码已提交，PR已存在或即将创建）之后，PR合并之前运行。你的任务：确保项目中的每个文档文件都准确、最新，并且采用友好的、以用户为中心的表述风格。

你大部分操作是自动化的。直接进行明显的事实性更新。仅在涉及风险或主观决策时才停止并询问用户。

仅在以下情况停止：

有风险/存疑的文档变更（叙述内容、理念、安全相关、删除内容、大规模重写）
VERSION版本号更新决策（如果尚未更新）
需要添加新的TODOS项
文档间存在叙述性矛盾（非事实性矛盾）

永远不要因以下情况停止：

差异内容明确显示的事实性修正
向表格/列表中添加内容
更新路径、计数、版本号
修复过时的交叉引用
CHANGELOG表述风格优化（小的措辞调整）
标记TODOS为已完成
文档间的事实性不一致（例如版本号不匹配）

绝对禁止：

覆盖、替换或重新生成CHANGELOG条目——仅优化措辞，保留所有内容
未询问用户就更新VERSION——版本变更必须通过AskUserQuestion确认
对CHANGELOG.md使用Write工具——始终使用Edit工具并精确匹配
```
old_string
```

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."
Gather context about what changed:

bash

git diff <base>...HEAD --stat

bash

git log <base>..HEAD --oneline

bash

git diff <base>...HEAD --name-only

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

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
Output a brief summary: "Analyzing N files changed across M commits. Found K documentation files to review."

检查当前分支。如果在基础分支上，终止操作：“你当前在基础分支上，请从功能分支运行此工作流。”
收集变更相关的上下文：

bash

git diff <base>...HEAD --stat

bash

git log <base>..HEAD --oneline

bash

git diff <base>...HEAD --name-only

发现仓库中的所有文档文件：

bash

find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.gstack/*" -not -path "./.context/*" | sort

将变更分类为与文档相关的类别：
- 新功能——新文件、新命令、新技能、新功能
- 行为变更——修改的服务、更新的API、配置变更
- 功能移除——删除的文件、移除的命令
- 基础设施——构建系统、测试基础设施、CI
输出简短摘要：“分析了M次提交中的N个变更文件。发现K个需要审核的文档文件。”

Step 2: Per-File Documentation Audit

步骤2：逐文档审计

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.

读取每个文档文件，并与差异内容交叉引用。使用以下通用准则（适用于任何项目——并非gstack专用）：

README.md：

是否描述了差异中显示的所有功能和特性？
安装/设置说明是否与变更一致？
示例、演示和使用说明是否仍然有效？
故障排除步骤是否仍然准确？

ARCHITECTURE.md：

ASCII图和组件描述是否与当前代码匹配？
设计决策和“为什么”的解释是否仍然准确？
保持谨慎——仅更新与差异明显矛盾的内容。架构文档描述的是不太可能频繁变更的内容。

CONTRIBUTING.md——新贡献者冒烟测试：

以全新贡献者的身份走完设置流程。
列出的命令是否准确？每个步骤是否能成功执行？
测试层级描述是否与当前测试基础设施匹配？
工作流描述（开发设置、贡献者模式等）是否最新？
标记任何会导致失败或让首次贡献者困惑的内容。

CLAUDE.md / 项目说明：

项目结构部分是否与实际文件树匹配？
列出的命令和脚本是否准确？
构建/测试说明是否与package.json（或等效文件）中的内容匹配？

其他.md文件：

读取文件，确定其用途和受众。
与差异内容交叉引用，检查是否存在矛盾。

对每个文件，将需要的更新分类为：

自动更新——差异内容明确需要的事实性修正：向表格中添加项、更新文件路径、修正计数、更新项目结构树。
询问用户——叙述内容变更、章节删除、安全模型变更、大规模重写（单个章节超过约10行）、相关性不明确、添加全新章节。

Step 3: Apply Auto-Updates

步骤3：应用自动更新

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

使用Edit工具直接进行所有明确的事实性更新。

对每个修改的文件，输出一行摘要，描述具体变更内容——不要只写“更新了README.md”，而是“README.md：在技能表格中添加了/new-skill，将技能数量从9更新为10。”

永远不要自动更新：

README的介绍或项目定位
ARCHITECTURE的理念或设计原理
安全模型描述
不要删除任何文档的整个章节

Step 4: Ask About Risky/Questionable Changes

步骤4：询问风险/存疑的变更

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.

对于步骤2中识别出的每个风险或存疑的更新，使用AskUserQuestion，包含：

上下文：项目名称、分支、哪个文档文件、正在审核的内容
具体的文档决策

RECOMMENDATION: 选择[X]，因为[一句话理由]

选项包括C) 跳过——保持原样

在用户回答后立即应用批准的变更。

Step 5: CHANGELOG Voice Polish

步骤5：CHANGELOG表述风格优化

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:

Read the entire CHANGELOG.md first. Understand what is already there.
Only modify wording within existing entries. Never delete, reorder, or replace entries.
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.
If an entry looks wrong or incomplete, use AskUserQuestion — do NOT silently fix it.
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.

关键规则——永远不要覆盖CHANGELOG条目。

此步骤仅优化表述风格，不重写、替换或重新生成CHANGELOG内容。

曾经发生过代理错误替换现有CHANGELOG条目的事件。本技能绝对不能犯同样的错误。

规则：

先完整阅读CHANGELOG.md，了解已有内容。
仅修改现有条目中的措辞。永远不要删除、重新排序或替换条目。
永远不要从头重新生成CHANGELOG条目。条目是由/ship根据实际差异和提交历史生成的，是事实来源。你只是优化表述，而非重写历史。
如果条目看起来错误或不完整，使用AskUserQuestion——不要默默修复。
使用Edit工具并精确匹配
```
old_string
```
——永远不要使用Write工具覆盖CHANGELOG.md。

如果此分支未修改CHANGELOG： 跳过此步骤。

如果此分支修改了CHANGELOG，审核条目的表述风格：

吸引力测试： 用户阅读每个项目符号时是否会想“哦，不错，我想试试”？如果不是，重写措辞（不改变内容）。
以用户现在可以做什么开头——而非实现细节。
使用“你现在可以...”而非“重构了...”
标记并重写任何看起来像提交信息的条目。
内部/贡献者变更应放在单独的“### 针对贡献者”小节中。
自动修复小的表述调整。如果重写会改变含义，使用AskUserQuestion。

Step 6: Cross-Doc Consistency & Discoverability Check

步骤6：跨文档一致性与可发现性检查

After auditing each file individually, do a cross-doc consistency pass:

Does the README's feature/capability list match what CLAUDE.md (or project instructions) describes?
Does ARCHITECTURE's component list match CONTRIBUTING's project structure description?
Does CHANGELOG's latest version match the VERSION file?
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.
Flag any contradictions between documents. Auto-fix clear factual inconsistencies (e.g., a version mismatch). Use AskUserQuestion for narrative contradictions.

在单独审核每个文件后，进行跨文档一致性检查：

README中的功能/特性列表是否与CLAUDE.md（或项目说明）中的描述匹配？
ARCHITECTURE中的组件列表是否与CONTRIBUTING中的项目结构描述匹配？
CHANGELOG的最新版本是否与VERSION文件匹配？
可发现性： 每个文档文件是否能从README.md或CLAUDE.md访问到？如果存在ARCHITECTURE.md但README和CLAUDE.md都没有链接到它，标记此问题。每个文档都应能从这两个入口文件之一找到。
标记文档间的任何矛盾。自动修复明确的事实性不一致（例如版本号不匹配）。对于叙述性矛盾，使用AskUserQuestion。

Step 7: TODOS.md Cleanup

步骤7：TODOS.md清理

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.

这是对/ship步骤5.5的补充。如果有

review/TODOS-format.md

，请阅读其中的标准TODO项格式。

如果TODOS.md不存在，跳过此步骤。

未标记为已完成的项： 将差异与未完成的TODO项交叉引用。如果某个TODO项明显被此分支的变更完成，将其移至已完成部分，并添加
```
**已完成：** vX.Y.Z.W (YYYY-MM-DD)
```
。保持谨慎——仅标记差异中有明确证据的项。
需要更新描述的项： 如果某个TODO项引用的文件或组件已发生重大变更，其描述可能已过时。使用AskUserQuestion确认是否应更新、完成或保留该TODO项。
新的待办工作： 检查差异中的
```
TODO
```
、
```
FIXME
```
、
```
HACK
```
和
```
XXX
```
注释。对于每个代表重要待办工作的注释（不是琐碎的内联注释），使用AskUserQuestion询问是否应将其记录到TODOS.md中。

Step 8: VERSION Bump Question

步骤8：VERSION版本号更新询问

CRITICAL — NEVER BUMP VERSION WITHOUT ASKING.

If VERSION does not exist: Skip silently.
Check if VERSION was already modified on this branch:

bash

git diff <base>...HEAD -- VERSION

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
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:
- 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.

关键规则——永远不要未询问用户就更新VERSION。

如果VERSION不存在： 静默跳过。
检查此分支是否已修改VERSION：

bash

git diff <base>...HEAD -- VERSION

如果VERSION未更新： 使用AskUserQuestion：
- RECOMMENDATION: 选择C（跳过），因为仅文档变更通常不需要版本更新
- A) 更新PATCH版本（X.Y.Z+1）——如果文档变更与代码变更一同发布
- B) 更新MINOR版本（X.Y+1.0）——如果这是一个重要的独立发布
- C) 跳过——不需要版本更新
如果VERSION已更新： 不要静默跳过。相反，检查更新是否覆盖了此分支的所有变更范围：
a. 读取当前VERSION的CHANGELOG条目。它描述了哪些功能？ b. 读取完整差异（
```
git diff <base>...HEAD --stat
```
和
```
git diff <base>...HEAD --name-only
```
）。是否有重大变更（新功能、新技能、新命令、主要重构）未在当前版本的CHANGELOG条目中提及？ c. 如果CHANGELOG条目覆盖了所有内容： 跳过——输出“VERSION：已更新至vX.Y.Z，覆盖所有变更。” d. 如果有未覆盖的重大变更： 使用AskUserQuestion解释当前版本覆盖的内容与新增内容，并询问：
- RECOMMENDATION: 选择A，因为新增变更值得拥有独立版本
- A) 更新至下一个PATCH版本（X.Y.Z+1）——为新增变更创建独立版本
- B) 保留当前版本——将新增变更添加到现有CHANGELOG条目中
- C) 跳过——保持版本不变，后续处理
核心原则：为“功能A”设置的版本更新不应默默包含“功能B”，如果功能B足够重要，值得拥有独立的版本条目。

Step 9: Commit & Output

步骤9：提交与输出

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:

Stage modified documentation files by name (never
```
git add -A
```
or
```
git add .
```
).
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 <noreply@anthropic.com>
EOF
)"

Push to the current branch:

bash

git push

PR body update (idempotent, race-safe):

Read the existing PR body into a PID-unique tempfile:

bash

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:

bash

gh pr edit --body-file /tmp/gstack-pr-body-$$.md

Clean up the tempfile:

bash

rm -f /tmp/gstack-pr-body-$$.md

If
```
gh pr view
```
fails (no PR exists): skip with message "No PR found — skipping body update."
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

先检查是否有变更： 运行

git status

（永远不要使用

-uall

）。如果之前的步骤未修改任何文档文件，输出“所有文档均已更新至最新状态。”并退出，不进行提交。

提交：

按名称暂存修改的文档文件（永远不要使用
```
git add -A
```
或
```
git add .
```
）。
创建单个提交：

bash

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
)"

推送到当前分支：

bash

git push

PR正文更新（幂等、防竞争）：

将现有PR正文读取到唯一的临时文件中：

bash

gh pr view --json body -q .body > /tmp/gstack-pr-body-$$.md

如果临时文件已包含
```
## Documentation
```
小节，用更新后的内容替换该小节。如果没有，在末尾添加
```
## Documentation
```
小节。
Documentation小节应包含文档差异预览——对每个修改的文件，描述具体变更内容（例如“README.md：在技能表格中添加了/document-release，将技能数量从9更新为10”）。
将更新后的正文写回：

bash

gh pr edit --body-file /tmp/gstack-pr-body-$$.md

清理临时文件：

bash

rm -f /tmp/gstack-pr-body-$$.md

如果
```
gh pr view
```
失败（不存在PR）：跳过并输出“未找到PR——跳过正文更新。”
如果
```
gh pr edit
```
失败：警告“无法更新PR正文——文档变更已提交至代码库。”并继续。

结构化文档健康状况摘要（最终输出）：

输出可快速扫描的摘要，显示每个文档文件的状态：

文档健康状况：
  README.md       [状态] ([详情])
  ARCHITECTURE.md [状态] ([详情])
  CONTRIBUTING.md [状态] ([详情])
  CHANGELOG.md    [状态] ([详情])
  TODOS.md        [状态] ([详情])
  VERSION         [状态] ([详情])

状态可选值：

Updated——附带变更描述
Current——无需变更
Voice polished——措辞已调整
Not bumped——用户选择跳过
Already bumped——版本由/ship设置
Skipped——文件不存在

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.

编辑前先阅读。 修改前务必完整阅读文件内容。
永远不要覆盖CHANGELOG。 仅优化措辞。永远不要删除、替换或重新生成条目。
永远不要静默更新VERSION。 始终询问用户。即使已更新，也要检查是否覆盖了所有变更范围。
明确说明变更内容。 每次编辑都要有一行摘要。
通用准则，而非项目专用。 审计检查适用于任何仓库。
可发现性很重要。 每个文档文件都应能从README或CLAUDE.md访问到。
表述风格：友好、以用户为中心、通俗易懂。 就像向没看过代码的聪明人解释一样。