Back to Details

review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Review

代码评审

Review code changes on the current branch by first reading checkpoint transcripts to understand the intent behind each change, then auditing the actual diff for issues. This produces an intent-aware review that catches mismatches between what the developer wanted and what the code actually does.
通过先读取checkpoint对话记录来理解每项变更的意图，再审核实际代码差异以排查问题，以此完成当前分支的代码变更评审。这种方式能生成感知意图的评审结果，捕捉开发者预期与代码实际表现之间的偏差。

Response Format

响应格式

Begin the first response to this skill invocation with the line:
Entire Review:
followed by a blank line, then the content.
  • Apply the header to the first response of the invocation only. Do not re-print it on follow-up turns within the same invocation.
  • Do not include the header on error or early-exit responses (e.g. "not a git repository", "no commits found between branch and base").
首次响应该技能调用时，需以如下行开头：
Entire Review:
随后空一行，再展示内容。
  • 仅在首次调用响应中添加上述标题。同一调用内的后续回复请勿重复打印该标题。
  • 错误或提前退出的响应（如“非git仓库”、“分支与基准分支间无提交记录”）请勿包含该标题。

Rules

规则

  1. This is a read-only audit. Do not modify any files during the review.
  2. Always show a scope banner before findings so the user knows what is being reviewed.
  3. If checkpoint context is unavailable, still perform the review using only the diff and commit messages. Clearly state that the review lacks intent context.
  4. Group findings by file. Within each file, order by severity (Critical > High > Medium > Low).
  5. Every finding must include a concrete suggestion or explanation, not just flag the issue.
  6. After presenting findings, ask the user if they want a fix plan. Do not auto-fix.
  7. Do not review generated files, lock files, or binary files unless the user explicitly asks for them.
  1. 这是一项只读审计操作。评审过程中请勿修改任何文件。
  2. 在展示评审结果前，需先显示范围提示栏，让用户明确评审对象。
  3. 若checkpoint上下文不可用，仍可仅通过代码差异和提交信息进行评审，并明确说明本次评审缺少意图上下文。
  4. 按文件分组展示评审结果。每个文件内的问题按严重程度排序（严重 > 高 > 中 > 低）。
  5. 每个问题都必须包含具体的建议或解释，不能仅标记问题。
  6. 展示完评审结果后，询问用户是否需要修复方案。请勿自动修复问题。
  7. 请勿评审生成文件、锁定文件或二进制文件，除非用户明确要求。

Process

流程

1. Verify environment

1. 验证环境

Run 
entire version
to check if the CLI is available. If it is not installed, note that the review will proceed without checkpoint intent context (degraded mode).
运行
entire version
命令检查CLI是否可用。若未安装，则说明评审将在缺少checkpoint意图上下文的降级模式下进行。

2. Detect base ref

2. 检测基准引用

Find the mainline branch to diff against. Try these refs in order and use the first that exists:
bash
git rev-parse --verify origin/HEAD 2>/dev/null
git rev-parse --verify origin/main 2>/dev/null
git rev-parse --verify origin/master 2>/dev/null
git rev-parse --verify main 2>/dev/null
git rev-parse --verify master 2>/dev/null
If none exist, tell the user no base ref was found and ask them to specify one.
找到用于对比的主线分支。按以下顺序尝试这些引用，使用第一个存在的引用：
bash
git rev-parse --verify origin/HEAD 2>/dev/null
git rev-parse --verify origin/main 2>/dev/null
git rev-parse --verify origin/master 2>/dev/null
git rev-parse --verify main 2>/dev/null
git rev-parse --verify master 2>/dev/null
若上述引用均不存在，告知用户未找到基准引用，并请用户指定一个。

3. Compute scope

3. 计算范围

bash
git rev-list --count <base>..HEAD
git diff --stat <base>..HEAD
Record the number of commits and files changed. This forms the scope banner.
bash
git rev-list --count <base>..HEAD
git diff --stat <base>..HEAD
记录提交次数和变更文件数，以此生成范围提示栏。

4. Gather checkpoint intent (skip in degraded mode)

4. 收集checkpoint意图（降级模式下跳过）

bash
git log --format='%H%x00%s%x00%b' <base>..HEAD
Extract 
Entire-Checkpoint:
trailer values from commit bodies. Deduplicate checkpoint IDs.
For each unique checkpoint ID (up to 20):
bash
entire explain --checkpoint <checkpoint-id> --json --no-pager
Parse the JSON to extract session metadata. For each non-review session in the checkpoint, prefer the summary (intent + outcome). If no summary is available, fall back to the latest user prompt. Truncate each checkpoint detail to 320 characters.
If 
--json
fails for a checkpoint, fall back to the bare human-readable output:
bash
entire explain --checkpoint <checkpoint-id> --no-pager
Do not use 
--full
in the review workflow — it produces long narrative text harder for agents to parse in bulk. If that also fails, skip the checkpoint and note it was unavailable.
Additionally, read the current in-progress session (if any) for uncommitted work context:
bash
entire session current --json
If this returns valid JSON, extract 
last_prompt
and 
files_touched
— these represent the intent behind uncommitted changes that are not yet captured in any checkpoint.
Build an intent map: for each file in the diff (committed + uncommitted), collect the relevant intent context from all checkpoints and the active session that touched it.
bash
git log --format='%H%x00%s%x00%b' <base>..HEAD
从提交内容中提取
Entire-Checkpoint:
尾部值，对checkpoint ID进行去重。
针对每个唯一的checkpoint ID（最多20个）：
bash
entire explain --checkpoint <checkpoint-id> --json --no-pager
解析JSON以提取会话元数据。对于checkpoint中的非评审会话，优先使用摘要（意图+结果）。若没有摘要，则退而使用最新的用户提示。将每个checkpoint的详情截断至320字符。
若
--json
参数对某个checkpoint失效，则退而使用纯人类可读的输出：
bash
entire explain --checkpoint <checkpoint-id> --no-pager
评审流程中请勿使用
--full
参数——它会生成冗长的叙述文本，不利于Agent批量解析。若该命令也失效，则跳过该checkpoint并说明其不可用。
此外，读取当前进行中的会话（若存在）以获取未提交工作的上下文：
bash
entire session current --json
若返回有效的JSON，提取
last_prompt
和
files_touched
——这些代表未提交变更的意图，尚未被任何checkpoint捕获。
构建意图映射：针对差异中的每个文件（已提交+未提交），收集所有涉及该文件的checkpoint和活动会话的相关意图上下文。

5. Read the diff

5. 读取代码差异

bash
git diff <base>..HEAD
Also include uncommitted changes:
bash
git diff HEAD
For large diffs (>5000 lines total), focus on the most critical files:
  • Files with the most changes
  • Files mentioned in checkpoint intents
  • Source files over generated/config files
Read individual file diffs as needed rather than loading the entire diff at once.
bash
git diff <base>..HEAD
同时包含未提交的变更：
bash
git diff HEAD
对于大型差异（总行数>5000），重点关注最关键的文件：
  • 变更最多的文件
  • checkpoint意图中提及的文件
  • 源文件优先于生成/配置文件
按需读取单个文件的差异，而非一次性加载全部差异。

6. Perform the review

6. 执行评审

Read the review rules:
references/review-rules.md
For each file in the diff, review it considering:
With checkpoint context:
  • Does the implementation match the stated intent?
  • Were the constraints from the transcript respected?
  • Did the agent miss edge cases it discussed?
  • Are there leftover debugging artifacts or TODOs?
Always (with or without context):
  • Logic errors, off-by-one, null safety
  • Security issues (injection, auth bypass, data exposure)
  • Performance concerns (N+1 queries, unnecessary allocations)
  • Error handling gaps
  • API contract violations
  • Dead code or unreachable branches
阅读评审规则：
references/review-rules.md
针对差异中的每个文件，结合以下要点进行评审：
有checkpoint上下文时：
  • 实现是否符合声明的意图？
  • 是否遵守了对话记录中的约束条件？
  • Agent是否遗漏了讨论过的边缘情况？
  • 是否存在残留的调试 artifacts 或 TODO标记？
无论是否有上下文，均需检查：
  • 逻辑错误、边界错误、空值安全性
  • 安全问题（注入、权限绕过、数据泄露）
  • 性能问题（N+1查询、不必要的内存分配）
  • 错误处理漏洞
  • API契约违反
  • 死代码或不可达分支

7. Output findings

7. 输出评审结果

Present findings using severity prefixes that align with the 
entire review --fix
parser:
Entire Review:

Reviewing <branch> vs <base>: N commits, M files changed
[Intent context: available from K checkpoints | unavailable — reviewing diff only]
使用与
entire review --fix
解析器一致的严重程度前缀展示结果：
Entire Review:

评审 <branch> 与 <base>：N次提交，M个文件变更
[意图上下文：来自K个checkpoint | 不可用——仅评审代码差异]

path/to/file.ts

path/to/file.ts

Critical: <issue description> Intent: <what the checkpoint said this should do, if available> Actual: <what the code actually does> Fix: <concrete suggestion>
High: <issue description> Intent: <what the checkpoint said this should do, if available> Actual: <what the code actually does> Fix: <concrete suggestion>
Medium: <improvement opportunity> Issue: <what is wrong> Fix: <concrete suggestion>
严重：<问题描述> 意图：<checkpoint中说明的预期功能（若可用）> 实际：<代码实际的表现> 修复建议：<具体建议>
高：<问题描述> 意图：<checkpoint中说明的预期功能（若可用）> 实际：<代码实际的表现> 修复建议：<具体建议>
中：<改进机会> 问题：<问题详情> 修复建议：<具体建议>

path/to/other-file.ts

path/to/other-file.ts

Low: <observation that is not a bug but worth noting>
Found N issues (X critical, Y high, Z medium, W low). Would you like me to create a fix plan for the critical and high issues?

When checkpoint context is unavailable for a finding, omit the `Intent:` line and use
`Issue:` / `Fix:` instead.
低：<值得注意的观察结果（非bug）>
共发现N个问题（X个严重，Y个高，Z个中，W个低）。 是否需要我针对严重和高优先级问题制定修复方案？

若某个问题无checkpoint上下文，则省略`意图：`行，改用`问题：`/`修复建议：`。

8. Offer follow-up

8. 提供后续操作选项

After presenting findings, wait for the user's response:
  • If they say yes to a fix plan, outline specific steps to address each critical/high issue.
  • If they ask to fix directly, switch to implementation mode and address the issues.
  • If they decline, the review is complete.
展示完评审结果后，等待用户回复：
  • 若用户同意生成修复方案，则列出解决每个严重/高优先级问题的具体步骤。
  • 若用户要求直接修复，则切换至实现模式并处理问题。
  • 若用户拒绝，则评审完成。

Degraded Mode (no Entire CLI or no checkpoints)

降级模式（无Entire CLI或无checkpoint）

When checkpoint context is unavailable:
  1. Skip step 4 entirely
  2. In the scope banner, state: "Intent context unavailable — reviewing diff only"
  3. Omit the "Intent:" line from findings
  4. Still perform the full code-level review from step 6
  5. Note at the end: "This review was performed without Entire checkpoint context. With checkpoints enabled, the review would also verify that implementation matches the original developer intent."
当checkpoint上下文不可用时：
  1. 完全跳过步骤4
  2. 在范围提示栏中说明：“意图上下文不可用——仅评审代码差异”
  3. 评审结果中省略“意图：”行
  4. 仍需执行步骤6中的完整代码级评审
  5. 在结尾说明：“本次评审未使用Entire checkpoint上下文。启用checkpoint后，评审还将验证实现是否符合开发者的原始意图。”

Failure Modes

失败场景

  • No commits between base and HEAD: Tell the user the branch has no changes relative to the base. Do not output a review.
  • Cannot detect base ref: Ask the user to specify the base branch or commit.
  • Diff too large (>100 files): Ask the user if they want to review all files or focus on a subset. Suggest reviewing only source files or files with checkpoint context.
  • entire explain
    fails    : Note the specific checkpoint was unavailable, continue reviewing remaining files without that context.
  • 基准分支与HEAD间无提交记录：告知用户该分支相对于基准分支无变更，无需输出评审结果。
  • 无法检测到基准引用：请用户指定基准分支或提交记录。
  • 差异过大（>100个文件）：询问用户是否要评审所有文件或聚焦于子集。建议仅评审源文件或有checkpoint上下文的文件。
  • entire explain
    命令失败    ：说明特定checkpoint不可用，继续评审其余文件（不使用该checkpoint的上下文）。