Back to Details

pr-review-guided

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Guided PR Review

引导式PR审查

A conversational, file-by-file PR review. The user drives the pace — you prepare everything upfront, then surface one file per turn.
一种对话式的逐文件PR审查方式。由用户主导节奏——你提前完成所有准备工作，然后每次展示一个文件。

Why this approach

这种方法的优势

Large PRs are overwhelming when dumped all at once. Reviewing smallest files first:
  • Builds context cheaply before hitting complex files
  • Lets the user ask questions or request skips without losing track
  • Surfaces the full picture before diving into 100-line diffs
大型PR一次性全部展示会让人无从下手。先审查变更最小的文件：
  • 在处理复杂文件前，以低成本构建上下文
  • 让用户可以随时提问或请求跳过文件，且不会迷失进度
  • 在深入查看百行级差异前，先了解整体情况

Phase 1: Preparation (do this all before showing any review)

第一阶段：准备工作（在展示任何审查内容前完成所有步骤）

1. Determine the PR

1. 确定PR信息

Accept a GitHub PR URL, PR number, or infer from the current branch. If none provided, ask.
接受GitHub PR URL、PR编号，或从当前分支推断。如果未提供任何信息，询问用户。

2. Establish review standards

2. 确立审查标准

First, look for a project-specific review instructions file:
bash
find . -name "PR_REVIEW_INSTRUCTIONS.md"
If found: read it strictly to extract content standards (severity labels, inline comment requirements, GitHub submission rules). The review process itself remains strictly governed by this skill: you must always execute the guided, file-by-file interactive flow as defined here.
If not found: check whether globally installed review skills are available. Look for any of these skill names: 
code-reviewer
, 
code-review
, 
caveman-review
, 
review
, 
pr-review
. Check the following locations in order, stopping at the first match:
ProviderPath
Universal (all providers)
~/.agents/skills/
Antigravity / Gemini
~/.gemini/config/skills/
Claude Code
~/.claude/commands/
Cursor (global)
~/.cursor/rules/
Cursor (project)
.cursor/rules/
If a matching skill file is found, load it and apply its standards as the review baseline. This ensures you inherit the user's preferred review style even without a project-specific config.
If neither exists: fall back to the default severity labels defined in the "Severity labels" section below.
首先，查找项目特定的审查说明文件：
bash
find . -name "PR_REVIEW_INSTRUCTIONS.md"
若找到：严格读取文件内容，提取内容标准（严重程度标签、行内注释要求、GitHub提交规则）。审查流程本身仍严格遵循本技能的定义：你必须始终执行此处规定的引导式、逐文件交互式流程。
若未找到：检查是否有全局安装的审查技能可用。查找以下任一技能名称：
code-reviewer
、
code-review
、
caveman-review
、
review
、
pr-review
。按以下顺序检查位置，找到第一个匹配项后停止：
提供商路径
Universal（所有提供商）
~/.agents/skills/
Antigravity / Gemini
~/.gemini/config/skills/
Claude Code
~/.claude/commands/
Cursor（全局）
~/.cursor/rules/
Cursor（项目）
.cursor/rules/
如果找到匹配的技能文件，加载并将其标准作为审查基线。这样即使没有项目特定配置，也能继承用户偏好的审查风格。
若两者都不存在：回退到下文“严重程度标签”部分定义的默认严重程度标签。

3. Fetch PR metadata

3. 获取PR元数据

Attempt to fetch the PR metadata using the following strategies in order:
  1. gh
    CLI    :
    bash
    gh pr view <PR_NUMBER> --json baseRefName,headRefName,title,body
  2. GitHub MCP: Call the 
    get_pull_request
    tool from the 
    github
    MCP server with the owner, repository name, and PR number.
  3. Local git branch info & User Prompt:
    • Infer the head branch using 
      git branch --show-current
      or 
      git log -n 1 --pretty=format:"%H"
      .
    • Ask the user for the base branch (defaulting to 
      main
      or 
      master
      if unknown).
    • Ask the user for the PR title and description, or read the recent commits with 
      git log -n 5
      .
Extract: title, base branch, head branch, description/requirements, and any acceptance criteria.
尝试按以下顺序使用不同策略获取PR元数据：
  1. gh
    CLI    ：
    bash
    gh pr view <PR_NUMBER> --json baseRefName,headRefName,title,body
  2. GitHub MCP： 调用
    github
    MCP服务器的
    get_pull_request
    工具，传入所有者、仓库名称和PR编号。
  3. 本地git分支信息 & 用户提示：
    • 使用
      git branch --show-current
      或
      git log -n 1 --pretty=format:"%H"
      推断头部分支。
    • 询问用户基准分支（若未知则默认
      main
      或
      master
      ）。
    • 询问用户PR标题和描述，或通过
      git log -n 5
      读取最近的提交记录。
提取信息：标题、基准分支、头部分支、描述/需求，以及任何验收标准。

4. Fetch and sort changed files

4. 获取并排序修改文件

Build a sorted list of all changed files by total lines changed (additions + deletions), ascending, including new and test files. Choose the first available method:
  1. gh
    CLI    : Run this single command to fetch and sort stats perfectly without downloading the raw diff:
    bash
    gh pr view <PR_NUMBER> --json files --jq '.files | sort_by(.additions + .deletions) | .[] | "\(.path) (+\(.additions) / -\(.deletions))"'
  2. GitHub MCP: Call 
    get_pull_request_files
    . Read the 
    changes
    property (or 
    additions
    + 
    deletions
    ) for each file in the JSON response, and sort the list in context.
  3. Local git: Parse the output of 
    git diff --stat origin/<base>...HEAD
    .
Once you have the sorted list, fetch the full PR diff (
gh pr diff <PR_NUMBER>
or 
git diff
) and save it to a scratch file for reference during the review.
构建所有修改文件的排序列表，按总变更行数（新增+删除）升序排列，包括新文件和测试文件。选择第一个可用的方法：
  1. gh
    CLI    ：运行以下单个命令即可完美获取并排序统计信息，无需下载原始差异：
    bash
    gh pr view <PR_NUMBER> --json files --jq '.files | sort_by(.additions + .deletions) | .[] | "\(.path) (+\(.additions) / -\(.deletions))"'
  2. GitHub MCP：调用
    get_pull_request_files
    。读取JSON响应中每个文件的
    changes
    属性（或
    additions
    + 
    deletions
    ），并在上下文中排序列表。
  3. 本地git：解析
    git diff --stat origin/<base>...HEAD
    的输出。
获取到排序后的列表后，获取完整的PR差异（
gh pr diff <PR_NUMBER>
或
git diff
）并保存到临时文件，供审查过程中参考。

5. Check environment

5. 检查环境

bash
cat .meteor/release   # or equivalent version file
Note the tech stack (framework version, language) to inform review standards.
bash
cat .meteor/release   # 或等效的版本文件
记录技术栈（框架版本、编程语言），为审查标准提供参考。

6. Present the file list

6. 展示文件列表

Show the complete sorted list with line counts before beginning reviews. This helps the user know what's coming and plan skips.
在开始审查前，展示完整的带行数统计的排序列表。这有助于用户了解待审查内容并规划跳过的文件。

Phase 2: Sequential Review

第二阶段：逐次审查

Present files one at a time using the fixed block format below. After each file, call 
ask_question
with the navigation menu — do not advance until the user responds.
每次展示一个文件，使用以下固定块格式。每个文件审查完成后，调用
ask_question
显示导航菜单——必须等待用户响应后再继续。

Per-file output block

单文件输出块

Output this exact structure for every file:
---
📄 File N/M · path/to/file.ts (+A / -D)

```diff
<diff content>
What it does: One sentence describing the change.
Issues:
  • [BUG] 
    line N
    — description. Fix: 
    exact fix
  • [WARNING] 
    line N
    — description. (Omit section entirely if no issues.)

Verdict: ✅ Correct | ⚠️ Minor issues | 🔴 Defect — fix before merge


Keep **What it does** to one sentence. For trivial files (type alias, import reorder) that sentence is the entire analysis — omit Issues and use `✅ Correct`.
每个文件都输出以下精确结构：
---
📄 文件 N/M · path/to/file.ts (+A / -D)

```diff
<diff content>
功能说明： 一句话描述变更内容。
问题：
  • [BUG] 
    第N行
    — 描述内容。修复方案：
    确切的修复代码
  • [WARNING] 
    第N行
    — 描述内容。 （若无问题则完全省略此部分。）

结论： ✅ 正确 | ⚠️ 轻微问题 | 🔴 缺陷 — 合并前需修复


**功能说明**部分限制为一句话。对于无关紧要的文件（类型别名、导入重排序），这句话即为完整分析——省略“问题”部分并使用`✅ 正确`。

Navigation menu

导航菜单

After outputting the block, call 
ask_question
with:
Question: "File N/M reviewed. What next?"
Options:
  - "➡️ Next file"
  - "⏭️ Skip next file"
  - "↩️ Go back to previous file"
  - "🏁 Done — show summary"
If the user writes a free-text comment instead of selecting, acknowledge it, apply any requested changes to the verdict, then show the menu again.
输出块后，调用
ask_question
显示：
Question: "已完成文件N/M的审查。下一步？"
Options:
  - "➡️ 下一个文件"
  - "⏭️ 跳过下一个文件"
  - "↩️ 返回上一个文件"
  - "🏁 完成 — 显示摘要"
如果用户未选择选项而是输入自由文本评论，先确认评论内容，根据请求修改结论，然后再次显示菜单。

Gather context — only if needed

收集上下文 — 仅在需要时

Read surrounding code only to confirm a real defect, not for curiosity. Good triggers:
  • Return type changed and a caller consumes it
  • Guard condition removed — is there another?
  • Schema field added — is it populated everywhere returned?
  • New DB query — does the project enforce async?
Read the minimum: the specific caller, schema, or related file. Don't explore.
仅在确认实际缺陷时才读取周边代码，而非出于好奇。合适的触发场景：
  • 返回类型变更且有调用方依赖
  • 移除了守卫条件——是否存在其他守卫？
  • 添加了模式字段——所有返回该字段的地方都已填充？
  • 新增了数据库查询——项目是否强制要求异步？
仅读取必要内容：特定调用方、模式或相关文件。不要进行无关探索。

Severity labels

严重程度标签

Follow any labels defined in 
PR_REVIEW_INSTRUCTIONS.md
. As defaults:
LabelMeaning
[BUG]Logic error, missing field, wrong condition — must fix
[WARNING]Potential issue that may or may not be a problem in practice
[SUGGESTION]Identifier naming, code smell, minor improvement
[NIT]Cosmetic, docs, trivial — report only if 3+ in same file
遵循
PR_REVIEW_INSTRUCTIONS.md
中定义的任何标签。默认规则如下：
标签含义
[BUG]逻辑错误、缺失字段、条件错误 — 必须修复
[WARNING]潜在问题，实际中可能会也可能不会引发故障
[SUGGESTION]标识符命名、代码异味、轻微改进建议
[NIT]格式美化、文档、无关紧要的细节 — 同一文件中出现3次及以上时才报告

Phase 3: End of Review

第三阶段：审查结束

When the user selects 🏁 Done or all files are reviewed, do the following in order:
当用户选择🏁 完成或所有文件审查完毕后，按以下顺序操作：

Step 1: Offer to revisit skipped files

步骤1：询问是否重新审查跳过的文件

If any files were skipped, call 
ask_question
before the summary:
Question: "You skipped N file(s): [list]. Revisit them now?"
Options:
  - "Yes — review skipped files"
  - "No — mark as intentionally skipped"
If yes: run the per-file block for each skipped file in original order. Update their verdict.
If no: mark them as 
⏭️ Intentionally skipped
in the summary.
若有文件被跳过，在显示摘要前调用
ask_question
：
Question: "你跳过了N个文件：[列表]。现在要重新审查它们吗？"
Options:
  - "是 — 审查跳过的文件"
  - "否 — 标记为主动跳过"
如果选择是：按原始顺序为每个跳过的文件运行单文件输出块。更新它们的结论。
如果选择否：在摘要中标记为
⏭️ 主动跳过
。

Step 2: Show the summary

步骤2：显示摘要

Once all decisions are made (including skipped file disposition):
  1. Show a summary table: file → verdict
  2. List open defects that need addressing before merge
  3. If 
    PR_REVIEW_INSTRUCTIONS.md
    or the fallback skill has GitHub submission rules, remind the user — don't post comments to GitHub unless they explicitly ask
所有决策完成后（包括跳过文件的处理）：
  1. 显示摘要表格：文件 → 结论
  2. 列出合并前需修复的未解决缺陷
  3. 如果
    PR_REVIEW_INSTRUCTIONS.md
    或回退技能中有GitHub提交规则，提醒用户——除非用户明确要求，否则不要向GitHub发布评论

Summary format

摘要格式

undefined
undefined

Review Summary

审查摘要

FileVerdict
types/common.ts✅ Correct
api/documents/helpers.ts⚠️ Minor issues
api/documentTypes/utils/getRefinementState.ts🔴 Defect — brand missing from active/ready state return
api/some/skipped-file.ts⏭️ Intentionally skipped
Defects to fix before merge:
  1. getRefinementState.ts
    — Add 
    brand
    to the final return block (lines 86-92)
Skipped:
  • api/some/skipped-file.ts
    — not reviewed by user's choice

---
文件结论
types/common.ts✅ 正确
api/documents/helpers.ts⚠️ 轻微问题
api/documentTypes/utils/getRefinementState.ts🔴 缺陷 — active/ready状态返回值中缺少brand字段
api/some/skipped-file.ts⏭️ 主动跳过
合并前需修复的缺陷：
  1. getRefinementState.ts
    — 在最终返回块中添加
    brand
    字段（第86-92行）
跳过的文件：
  • api/some/skipped-file.ts
    — 用户选择未审查

---

Notes on efficiency

效率提示

  • The sorted-ascending order is not just UX — it builds your own context incrementally. Trivial files (type additions, test registrations) tell you what concepts the PR introduces before you hit the meaty service files.
  • When you spot a defect in an early file, keep track of it. It often shows up again (correctly or incorrectly) in later files.
  • If the PR description has acceptance criteria, use them as a checklist. Note which are covered and which aren't as you go.
  • 升序排序不仅是用户体验优化——还能帮助你逐步构建上下文。无关紧要的文件（类型新增、测试注册）会在你处理核心服务文件前，告诉你PR引入的概念。
  • 若在早期文件中发现缺陷，请记录下来。该缺陷通常会在后续文件中再次出现（可能修复也可能未修复）。
  • 如果PR描述中有验收标准，将其作为检查清单。在审查过程中记录哪些标准已覆盖，哪些未覆盖。