review

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 <old> <new>

：请阅读

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

并按照「内联升级流程」操作（若已配置自动升级则自动执行，否则向用户展示4个选项的问题，若用户拒绝则记录暂缓状态）。如果输出显示

JUST_UPGRADED <from> <to>

：告知用户「当前运行gstack v{to}（刚刚完成更新！）」并继续后续操作。

AskUserQuestion Format

向用户提问的格式

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未将表达式包裹在async上下文中而报错

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团队——我在使用/{skill-name}时遇到了这个问题：

我尝试做的事情： {用户/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版本} | 技能： /{skill}


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

命令中，凡提到「基准分支」的地方，均替换为检测到的分支名称。

Pre-Landing PR Review

PR合并前审查

You are running the

/review

workflow. Analyze the current branch's diff against the base branch for structural issues that tests don't catch.

你正在运行

/review

工作流程。分析当前分支与基准分支的代码差异，找出测试无法覆盖的结构性问题。

Step 1: Check branch

步骤1：检查分支

Run
```
git branch --show-current
```
to get the current branch.
If on the base branch, output: "Nothing to review — you're on the base branch or have no changes against it." and stop.
Run
```
git fetch origin <base> --quiet && git diff origin/<base> --stat
```
to check if there's a diff. If no diff, output the same message and stop.

运行
```
git branch --show-current
```
获取当前分支。
如果当前处于基准分支，输出：「无可审查内容——你当前处于基准分支，或与基准分支无代码差异。」 并停止流程。
运行
```
git fetch origin <base> --quiet && git diff origin/<base> --stat
```
检查是否存在代码差异。如果无差异，输出相同消息并停止。

Step 2: Read the checklist

步骤2：阅读检查清单

Read

.claude/skills/review/checklist.md

If the file cannot be read, STOP and report the error. Do not proceed without the checklist.

读取

.claude/skills/review/checklist.md

文件。

如果无法读取该文件，立即停止并报告错误。 没有检查清单不得继续。

Step 2.5: Check for Greptile review comments

步骤2.5：检查Greptile审查评论

Read

.claude/skills/review/greptile-triage.md

and follow the fetch, filter, classify, and escalation detection steps.

If no PR exists,
gh
fails, API returns an error, or there are zero Greptile comments: Skip this step silently. Greptile integration is additive — the review works without it.

If Greptile comments are found: Store the classifications (VALID & ACTIONABLE, VALID BUT ALREADY FIXED, FALSE POSITIVE, SUPPRESSED) — you will need them in Step 5.

读取

.claude/skills/review/greptile-triage.md

并按照获取、过滤、分类以及升级检测步骤操作。

如果PR不存在、
gh
命令失败、API返回错误，或没有Greptile评论：静默跳过此步骤。Greptile集成是附加功能——即使没有它，审查工作也能正常进行。

如果找到Greptile评论： 保存分类结果（VALID & ACTIONABLE、VALID BUT ALREADY FIXED、FALSE POSITIVE、SUPPRESSED）——后续步骤5会用到这些信息。

Step 3: Get the diff

步骤3：获取代码差异

Fetch the latest base branch to avoid false positives from stale local state:

bash

git fetch origin <base> --quiet

Run

git diff origin/<base>

to get the full diff. This includes both committed and uncommitted changes against the latest base branch.

拉取最新的基准分支，避免因本地状态过时导致误报：

bash

git fetch origin <base> --quiet

运行

git diff origin/<base>

获取完整的代码差异。这包括相对于最新基准分支的已提交和未提交更改。

Step 4: Two-pass review

步骤4：两轮审查

Apply the checklist against the diff in two passes:

Pass 1 (CRITICAL): SQL & Data Safety, Race Conditions & Concurrency, LLM Output Trust Boundary, Enum & Value Completeness
Pass 2 (INFORMATIONAL): Conditional Side Effects, Magic Numbers & String Coupling, Dead Code & Consistency, LLM Prompt Issues, Test Gaps, View/Frontend

Enum & Value Completeness requires reading code OUTSIDE the diff. When the diff introduces a new enum value, status, tier, or type constant, use Grep to find all files that reference sibling values, then Read those files to check if the new value is handled. This is the one category where within-diff review is insufficient.

Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section.

对照检查清单对代码差异进行两轮审查：

第一轮（CRITICAL，关键问题）： SQL与数据安全性、竞争条件与并发、LLM输出信任边界、枚举与值完整性
第二轮（INFORMATIONAL，信息性问题）： 条件副作用、魔法数字与字符串耦合、死代码与一致性、LLM提示问题、测试缺口、视图/前端

枚举与值完整性需要读取代码差异之外的代码。 当差异引入新的枚举值、状态、层级或类型常量时，使用Grep查找所有引用同级值的文件，然后读取这些文件检查新值是否已被处理。这是唯一仅靠差异内审查不足以覆盖的类别。

遵循检查清单中指定的输出格式。尊重抑制规则——不得标记「请勿标记」部分列出的项。

Step 5: Output findings

步骤5：输出审查结果

Always output ALL findings — both critical and informational. The user must see every issue.

If CRITICAL issues found: output all findings, then for EACH critical issue use a separate AskUserQuestion with the problem, then
```
RECOMMENDATION: Choose A because [one-line reason]
```
, then options (A: Fix it now, B: Acknowledge, C: False positive — skip). After all critical questions are answered, output a summary of what the user chose for each issue. If the user chose A (fix) on any issue, apply the recommended fixes. If only B/C were chosen, no action needed.
If only non-critical issues found: output findings. No further action needed.
If no issues found: output
```
Pre-Landing Review: No issues found.
```

必须输出所有审查结果——包括关键问题和信息性问题。用户必须看到所有问题。

如果发现关键问题：输出所有结果，然后针对每个关键问题单独使用AskUserQuestion展示问题，接着给出
```
RECOMMENDATION: 选择A，因为[一句话理由]
```
，再提供选项（A：立即修复，B：已知晓，C：误报——跳过）。在所有关键问题的回复完成后，输出用户对每个问题的选择总结。如果用户选择A（修复）任何问题，执行推荐的修复操作。如果仅选择B/C，则无需操作。
如果仅发现非关键问题：输出结果。无需进一步操作。
如果未发现问题：输出
```
Pre-Landing Review: 未发现问题。
```

Greptile comment resolution

Greptile评论处理

After outputting your own findings, if Greptile comments were classified in Step 2.5:

Include a Greptile summary in your output header:

+ N Greptile comments (X valid, Y fixed, Z FP)

Before replying to any comment, run the Escalation Detection algorithm from greptile-triage.md to determine whether to use Tier 1 (friendly) or Tier 2 (firm) reply templates.

VALID & ACTIONABLE comments: These are already included in your CRITICAL findings — they follow the same AskUserQuestion flow (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses A (fix), reply using the Fix reply template from greptile-triage.md (include inline diff + explanation). If the user chooses C (false positive), reply using the False Positive reply template (include evidence + suggested re-rank), save to both per-project and global greptile-history.
FALSE POSITIVE comments: Present each one via AskUserQuestion:
- Show the Greptile comment: file:line (or [top-level]) + body summary + permalink URL
- Explain concisely why it's a false positive
- Options:
  - A) Reply to Greptile explaining why this is incorrect (recommended if clearly wrong)
  - B) Fix it anyway (if low-effort and harmless)
  - C) Ignore — don't reply, don't fix
If the user chooses A, reply using the False Positive reply template from greptile-triage.md (include evidence + suggested re-rank), save to both per-project and global greptile-history.
VALID BUT ALREADY FIXED comments: Reply using the Already Fixed reply template from greptile-triage.md — no AskUserQuestion needed:
- Include what was done and the fixing commit SHA
- Save to both per-project and global greptile-history
SUPPRESSED comments: Skip silently — these are known false positives from previous triage.

在输出自己的审查结果后，如果步骤2.5中已对Greptile评论进行分类：

在输出头部添加Greptile摘要：

+ N条Greptile评论（X条有效且可操作，Y条已修复，Z条误报）

回复任何评论前，运行greptile-triage.md中的升级检测算法，确定使用Tier 1（友好）还是Tier 2（正式）回复模板。

VALID & ACTIONABLE（有效且可操作）评论： 这些已包含在你的关键问题结果中——遵循相同的AskUserQuestion流程（A：立即修复，B：已知晓，C：误报）。如果用户选择A（修复），使用greptile-triage.md中的「修复回复模板」回复（包含内联差异+解释）。如果用户选择C（误报），使用「误报回复模板」回复（包含证据+建议重新排序），并保存到项目级和全局greptile-history。
FALSE POSITIVE（误报）评论： 通过AskUserQuestion展示每个评论：
- 显示Greptile评论：文件:行（或[顶级]）+ 内容摘要+ 永久链接URL
- 简要解释为何是误报
- 选项：
  - A) 回复Greptile解释错误原因（若明显错误则推荐此选项）
  - B) 无论如何修复（若工作量小且无危害）
  - C) 忽略——不回复，不修复
如果用户选择A，使用greptile-triage.md中的「误报回复模板」回复（包含证据+建议重新排序），并保存到项目级和全局greptile-history。
VALID BUT ALREADY FIXED（有效但已修复）评论： 使用greptile-triage.md中的「已修复回复模板」回复——无需AskUserQuestion：
- 说明已完成的操作和修复提交的SHA
- 保存到项目级和全局greptile-history
SUPPRESSED（已抑制）评论： 静默跳过——这些是之前分类过的已知误报。

Step 5.5: TODOS cross-reference

步骤5.5：TODO项交叉引用

Read

TODOS.md

in the repository root (if it exists). Cross-reference the PR against open TODOs:

Does this PR close any open TODOs? If yes, note which items in your output: "This PR addresses TODO: <title>"
Does this PR create work that should become a TODO? If yes, flag it as an informational finding.
Are there related TODOs that provide context for this review? If yes, reference them when discussing related findings.

If TODOS.md doesn't exist, skip this step silently.

读取仓库根目录的

TODOS.md

（如果存在）。将PR与未完成的TODO项进行交叉引用：

此PR是否解决了任何未完成的TODO项？ 如果是，在输出中注明：「此PR解决了TODO：<标题>」
此PR是否产生了应添加为TODO的工作？ 如果是，标记为信息性问题。
是否有相关的TODO项可为此次审查提供上下文？ 如果是，在讨论相关结果时引用这些TODO项。

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

Step 5.6: Documentation staleness check

步骤5.6：文档过时检查

Cross-reference the diff against documentation files. For each

.md

file in the repo root (README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, etc.):

Check if code changes in the diff affect features, components, or workflows described in that doc file.
If the doc file was NOT updated in this branch but the code it describes WAS changed, flag it as an INFORMATIONAL finding: "Documentation may be stale: [file] describes [feature/component] but code changed in this branch. Consider running
```
/document-release
```
."

This is informational only — never critical. The fix action is

/document-release

If no documentation files exist, skip this step silently.

将代码差异与文档文件进行交叉引用。对于仓库根目录中的每个

.md

文件（README.md、ARCHITECTURE.md、CONTRIBUTING.md、CLAUDE.md等）：

检查差异中的代码更改是否影响该文档中描述的功能、组件或工作流程。
如果该文档未在此分支中更新，但它描述的代码已更改，标记为信息性问题： "文档可能已过时：[文件]描述了[功能/组件]，但此分支中代码已更改。考虑运行
```
/document-release
```
。"

这仅为信息性提示——永远不会是关键问题。修复操作是运行

/document-release

。

如果没有文档文件，静默跳过此步骤。

Important Rules

重要规则

Read the FULL diff before commenting. Do not flag issues already addressed in the diff.
Read-only by default. Only modify files if the user explicitly chooses "Fix it now" on a critical issue. Never commit, push, or create PRs.
Be terse. One line problem, one line fix. No preamble.
Only flag real problems. Skip anything that's fine.
Use Greptile reply templates from greptile-triage.md. Every reply includes evidence. Never post vague replies.

在评论前阅读完整的代码差异。 不要标记差异中已解决的问题。
默认仅读取。 只有当用户明确选择「立即修复」关键问题时，才修改文件。绝不要提交、推送或创建PR。
保持简洁。 一句话描述问题，一句话描述修复。无需开场白。
仅标记真实问题。 跳过任何无问题的内容。
使用greptile-triage.md中的Greptile回复模板。 每个回复都包含证据。绝不要发布模糊的回复。