Back to Details

walkthrough-pr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

walkthrough-pr

walkthrough-pr

Produce one continuous, readable PR review the user can read top-to-bottom. Same shape as 
walkthrough
, plus a much heavier scrutiny pass. The user can have uncommitted changes in their main working tree — this skill never touches it.
生成一份连贯易读的PR审查报告，方便用户从头到尾阅读。与
walkthrough
的结构一致，但审查力度更强。用户的主工作树中可以存在未提交的更改——本技能绝不会触碰主工作树。

Resolve scope

确定范围

Arguments: 
<pr-branch> [dest-branch]
. 
pr-branch
is required.
Resolve 
pr-branch
:
  1. Try 
    git rev-parse --verify <pr-branch>
    .
  2. If that fails, run 
    git fetch
    once, then retry as 
    <pr-branch>
    and 
    origin/<pr-branch>
    . Use whichever resolves.
  3. If still unresolved, stop and ask the user.
Resolve 
dest-branch
:
  • If passed explicitly, use it (resolve same way as 
    pr-branch
    ).
  • Otherwise, run 
    git symbolic-ref refs/remotes/origin/HEAD
    (yields 
    refs/remotes/origin/<name>
    ).
  • If that fails (origin/HEAD not set), stop and ask the user. Do not guess 
    main
    / 
    master
    / 
    develop
    — better to ask than review against the wrong base.
Capture the PR head SHA via 
git rev-parse <pr-branch>
for use in output and verification.
参数：
<pr-branch> [dest-branch]
。
pr-branch
为必填项。
解析
pr-branch
：
  1. 尝试执行
    git rev-parse --verify <pr-branch>
    。
  2. 如果执行失败，先运行
    git fetch
    ，然后分别尝试解析
    <pr-branch>
    和
    origin/<pr-branch>
    ，使用解析成功的那个。
  3. 如果仍无法解析，停止操作并询问用户。
解析
dest-branch
：
  • 如果用户明确传入，使用该分支（解析方式与
    pr-branch
    相同）。
  • 否则，执行
    git symbolic-ref refs/remotes/origin/HEAD
    （返回结果为
    refs/remotes/origin/<name>
    ）。
  • 如果执行失败（未设置origin/HEAD），停止操作并询问用户。请勿猜测
    main
    /
    master
    /
    develop
    分支——与其审查错误的基准分支，不如询问用户。
通过
git rev-parse <pr-branch>
获取PR头部的SHA值，用于输出和验证。

Set up the worktree

设置工作树

The review reads files from a detached worktree at 
<repo-root>/.pr-review/<branch-slug>/
. The main working tree is never touched.
<branch-slug>
is the PR branch name with characters illegal in folder names (notably 
/
, plus 
\
, 
:
, 
*
, 
?
, 
"
, 
<
, 
>
, 
|
) replaced with 
-
. Examples: 
feature/login-fix
→ 
feature-login-fix
; 
bugfix/JIRA-123
→ 
bugfix-JIRA-123
. Strip any leading 
origin/
first if the user passed a remote-tracking ref.
  1. First-run hygiene: ensure 
    .pr-review/
    is in 
    .git/info/exclude
    . Read the file; if the line 
    .pr-review/
    is missing, append it. (
    .git/info/exclude
    is per-repo and not committed, so this doesn't churn the team's 
    .gitignore
    .)
  2. Clear the same-branch worktree if present: if 
    <repo-root>/.pr-review/<branch-slug>/
    already exists, run 
    git worktree remove --force .pr-review/<branch-slug>
    (check with 
    git worktree list
    first; ignore errors if absent). Other branches' worktrees are left untouched.
  3. Create the worktree: 
    git worktree add --detach .pr-review/<branch-slug> <pr-branch-ref>
    . Detached HEAD avoids "already checked out" errors when the PR branch happens to be checked out elsewhere.
The worktree stays alive after the skill finishes so clickable links in the review remain navigable. Re-running 
/walkthrough-pr
for the same branch overwrites it; different branches accumulate side-by-side under 
.pr-review/
. The user can list them with 
git worktree list
and prune stale ones with 
git worktree remove --force .pr-review/<branch-slug>
.
审查将从位于
<repo-root>/.pr-review/<branch-slug>/
的分离式工作树中读取文件。主工作树绝不会被触碰。
<branch-slug>
是将PR分支名称中非法文件夹字符（主要是
/
，还有
\
、
:
、
*
、
?
、
"
、
<
、
>
、
|
）替换为
-
后的名称。示例：
feature/login-fix
→ 
feature-login-fix
；
bugfix/JIRA-123
→ 
bugfix-JIRA-123
。如果用户传入的是远程跟踪引用，需先移除开头的
origin/
。
  1. 首次运行清理：确保
    .pr-review/
    已添加到
    .git/info/exclude
    中。读取该文件；如果缺少
    .pr-review/
    这一行，则追加进去。（
    .git/info/exclude
    是仓库级别的配置，不会被提交，因此不会影响团队的
    .gitignore
    文件。）
  2. 清除已存在的同分支工作树：如果
    <repo-root>/.pr-review/<branch-slug>/
    已存在，执行
    git worktree remove --force .pr-review/<branch-slug>
    （先通过
    git worktree list
    检查；如果不存在则忽略错误）。其他分支的工作树将保持不变。
  3. 创建工作树：执行
    git worktree add --detach .pr-review/<branch-slug> <pr-branch-ref>
    。分离头指针可以避免当PR分支已在其他地方被检出时出现的“已检出”错误。
本技能完成后，工作树会保持存在，以便审查报告中的可点击链接仍能正常访问。针对同一分支重新运行
/walkthrough-pr
会覆盖原有工作树；不同分支的工作树会在
.pr-review/
下并存。用户可以通过
git worktree list
查看所有工作树，通过
git worktree remove --force .pr-review/<branch-slug>
清理过期的工作树。

Gather

收集信息

All git commands run from the main repo (refs work without entering the worktree):
  1. git diff --stat <dest-branch>...<pr-branch>
    — file list and line counts.
  2. git diff <dest-branch>...<pr-branch>
    — full diff. Three-dot range — compares PR head against the merge-base with dest, i.e. only what this PR introduces. Don't use two-dot.
  3. git log <dest-branch>..<pr-branch> --format='%s%n%n%b'
    — PR commit messages (two-dot here for the linear commit list). Author intent is a strong signal even when the code is opaque.
When you need surrounding context that isn't in the diff (e.g. to see how a touched function is called elsewhere), 
Read
files via absolute paths under 
<repo-root>/.pr-review/<branch-slug>/...
. Don't 
Read
from the main tree — that's the user's working state, not the PR's.
所有git命令都在主仓库中执行（无需进入工作树即可操作引用）：
  1. git diff --stat <dest-branch>...<pr-branch>
    —— 文件列表和行数统计。
  2. git diff <dest-branch>...<pr-branch>
    —— 完整差异。使用三点范围——对比PR头部与目标分支的合并基准，即仅显示该PR引入的更改。请勿使用两点范围。
  3. git log <dest-branch>..<pr-branch> --format='%s%n%n%b'
    —— PR的提交信息（此处使用两点范围获取线性提交列表）。即使代码难以理解，作者的意图也是重要的参考信号。
当需要差异中未包含的上下文信息时（例如查看被修改的函数在其他地方的调用方式），通过
<repo-root>/.pr-review/<branch-slug>/...
下的绝对路径
Read
文件。请勿从主工作树
Read
文件——主工作树是用户的当前工作状态，而非PR的状态。

Decide reading order

确定阅读顺序

Same heuristic as walkthrough — bottom-up by dependency:
  1. Schema / migrations / types / data models
  2. Pure utilities and shared helpers
  3. Core business logic (services, domain modules)
  4. Glue / handlers / controllers / API routes
  5. UI / views / templates / styles
  6. Tests
  7. Config, fixtures, docs, snapshots, lockfiles
Deviate when one file is clearly the entry point of the change — lead with it and treat the rest as supporting context. State the chosen order and reason up front.
采用与walkthrough相同的启发式规则——按依赖关系自底向上：
  1. Schema / 迁移文件 / 类型定义 / 数据模型
  2. 纯工具函数和共享助手
  3. 核心业务逻辑（服务、领域模块）
  4. 粘合层 / 处理器 / 控制器 / API路由
  5. UI / 视图 / 模板 / 样式
  6. 测试代码
  7. 配置、测试数据、文档、快照、锁文件
当某个文件明显是更改的入口点时，可以调整顺序——先讲解该文件，其余文件作为支撑上下文。在报告开头说明选定的顺序及原因。

Linking to lines

代码行链接

Whenever you call out specific code, link to it with a line-anchored markdown link pointing into the worktree, not the main repo. Clicking opens the actual PR-state file.
Format:
  • Single line: 
    [validateInput](.pr-review/<branch-slug>/src/foo.ts#L42)
    or 
    [src/foo.ts:42](.pr-review/<branch-slug>/src/foo.ts#L42)
  • Range: 
    [the new error branch](.pr-review/<branch-slug>/src/foo.ts#L42-L58)
Pick line numbers from the post-change side of the diff — the 
+A
in each 
@@ -X,Y +A,B @@
hunk header, then count down. Those numbers match the file at the PR head, which is what the worktree contains.
For deletions, there's no "after" line to link — describe the removal in prose and link surrounding context. Don't fabricate anchors.
Use prose link text ("the new error branch", "
validateInput
") rather than raw 
path:42
whenever it reads better.
每当提及特定代码时，使用锚定到行号的markdown链接指向工作树中的文件，而非主仓库。点击链接将打开PR状态下的实际文件。
格式：
  • 单行：
    [validateInput](.pr-review/<branch-slug>/src/foo.ts#L42)
    或 
    [src/foo.ts:42](.pr-review/<branch-slug>/src/foo.ts#L42)
  • 多行范围：
    [新的错误分支](.pr-review/<branch-slug>/src/foo.ts#L42-L58)
行号从差异的变更后部分获取——即每个
@@ -X,Y +A,B @@
块头中的
+A
，然后向下计数。这些行号与PR头部的文件一致，也就是工作树中文件的行号。
对于删除的代码，没有“变更后”的行号可链接——用文字描述删除内容，并链接周围的上下文。请勿伪造锚点。
尽可能使用描述性的链接文本（如“新的错误分支”、“
validateInput
”），而非原始的
path:42
格式，以提升可读性。

Write the review

撰写审查报告

Compose the review as one continuous markdown document, then save and display it:
  1. Save the full content to 
    <repo-root>/.pr-review/<branch-slug>/WALKTHROUGH.md
    using the 
    Write
    tool. This is the shareable artifact — the user can copy/paste the file into a Bitbucket comment, Slack, etc.
  2. Display the exact same content inline in chat — no pagination, no "say next to continue". The chat output and the file content must be identical (single source of truth).
State up front in the document: "Links open files in 
.pr-review/<branch-slug>/
, which holds the PR branch state. The worktree is overwritten on the next 
/walkthrough-pr
run for this same branch." Substitute the real branch slug in the actual output — readers should see a concrete path.
将审查报告撰写为一份连贯的markdown文档，然后保存并展示：
  1. 保存：使用
    Write
    工具将完整内容保存到
    <repo-root>/.pr-review/<branch-slug>/WALKTHROUGH.md
    。这是可共享的成果——用户可以将该文件复制粘贴到Bitbucket评论、Slack等平台。
  2. 展示：在聊天中直接显示完整内容——无需分页，无需提示“继续查看下一部分”。聊天输出与文件内容必须完全一致（单一数据源）。
在文档开头说明：“链接将打开
.pr-review/<branch-slug>/
中的文件，该目录保存着PR分支的状态。针对同一分支再次运行
/walkthrough-pr
时，该工作树会被覆盖。” 在实际输出中替换为真实的分支slug——读者应看到具体的路径。

1. Overview (2–3 sentences)

1. 概述（2-3句话）

What this PR does and why, inferred from the code, commit messages, and any new tests. Mention the PR branch, the dest branch, the head SHA, and rough size (e.g. "9 files, ~240 lines added across X, Y, Z, against 
main
(PR head 
abc1234
)").
说明该PR的功能和目的，从代码、提交信息和新增测试中推断而来。提及PR分支、目标分支、头部SHA值和大致规模（例如：“9个文件，在X、Y、Z模块中新增约240行代码，基准分支为
main
（PR头部SHA为
abc1234
）”）。

2. Reading order

2. 阅读顺序

Short numbered list naming the files in the order you'll cover them, with a brief reason for the grouping.
简短的编号列表，列出将要讲解的文件顺序，并简要说明分组原因。

3. File-by-file

3. 逐文件讲解

One section per file (or per group, for trivial files). Each section:
  • Heading: clickable worktree path, e.g. 
    [.pr-review/<branch-slug>/src/foo.ts](.pr-review/<branch-slug>/src/foo.ts)
    , plus a one-line role ("new domain entity for X", "wires the new entity into the API layer", etc.). Keep the heading link file-level — line-anchored links go inline in the body.
  • What changed — a summary, not a re-paste of the diff.
  • Why — inferred intent; flag uncertainty.
  • Scrutinize — anything non-obvious, risky, or worth a second look. Omit when there's nothing to flag.
每个文件（或一组无关紧要的文件）对应一个章节：
  • 标题：可点击的工作树路径，例如
    [.pr-review/<branch-slug>/src/foo.ts](.pr-review/<branch-slug>/src/foo.ts)
    ，加上一行描述（如“X的新领域实体”、“将新实体接入API层”等）。标题链接为文件级——行锚定链接放在正文内。
  • 变更内容——摘要，而非复制粘贴差异。
  • 变更意图——推断的目的；如有不确定需标注。
  • 审查意见——任何不明显、有风险或值得再次检查的内容。如果没有需要标注的内容则省略。

4. Things to scrutinize (heavy pass)

4. 重点审查项（严格检查）

A final section with cross-file concerns. Walk through each category below explicitly — even briefly stating "nothing here" — so nothing gets quietly skipped:
  • Logic bugs & off-by-ones — boundary conditions, inverted comparisons, wrong loop variables.
  • Tests — missing coverage for new branches; tests that assert nothing meaningful (e.g. only checking that something didn't throw); deleted tests; snapshot churn that hides logic changes.
  • Error handling — swallowed exceptions, generic catches, missing fallbacks at boundaries (network, FS, deserialization), error states that silently succeed.
  • Edge cases — empty inputs, nulls/undefined, zero-length collections, concurrency / race conditions, retry behavior, idempotency.
  • Security — secrets in code or config, injection (SQL/shell/HTML), auth bypass, missing authz checks, unsafe deserialization, SSRF, prompt injection in LLM contexts.
  • Scope creep — drive-by changes unrelated to the PR's stated intent; refactors mixed with feature work; formatting churn obscuring real changes.
  • Accidental reverts — code that re-introduces something previously removed; stale code paths revived.
  • Dependency changes — new packages, version bumps (especially major), unexpected lockfile churn, transitive risk.
  • API / contract breaks — renamed/removed exports, changed function signatures, response shape changes — and whether call sites elsewhere in the repo were updated.
  • Performance — N+1 queries, unbounded loops, sync I/O on hot paths, unneeded re-renders, large allocations in tight loops.
  • Hallucinated APIs — calls to functions/methods that don't exist on the imported module (especially common in AI-generated PRs). Verify by 
    Read
    ing the imported module from the worktree when in doubt.
  • Leftovers — TODOs, debug logging, 
    console.log
    , commented-out code, dead branches.
If a category genuinely has nothing, say so in one phrase ("Tests: comprehensive, asserts the new branch."). If everything is clean, end with one sentence saying so.
最后一个章节涵盖跨文件的问题。需明确检查以下每个类别——即使简要说明“无问题”也可，避免遗漏任何项：
  • 逻辑bug与边界错误——边界条件、反向比较、错误的循环变量。
  • 测试代码——新增分支缺少测试覆盖；无实际意义的测试断言（如仅检查未抛出异常）；被删除的测试；快照变更掩盖逻辑修改。
  • 错误处理——被吞掉的异常、通用捕获语句、边界处缺少回退机制（网络、文件系统、反序列化）、静默成功的错误状态。
  • 边缘情况——空输入、null/undefined、零长度集合、并发/竞态条件、重试行为、幂等性。
  • 安全性——代码或配置中的密钥、注入攻击（SQL/Shell/HTML）、认证绕过、缺少授权检查、不安全的反序列化、SSRF、LLM场景中的提示注入。
  • 范围蔓延——与PR既定意图无关的顺带修改；重构与功能开发混合；格式变更掩盖真实修改。
  • 意外回滚——重新引入之前已移除的代码；激活陈旧的代码路径。
  • 依赖变更——新增包、版本升级（尤其是大版本）、意外的锁文件变更、传递性风险。
  • API/契约破坏——重命名/移除导出、函数签名变更、响应结构变更——以及仓库中其他调用位置是否已更新。
  • 性能问题——N+1查询、无界循环、热点路径上的同步I/O、不必要的重渲染、循环中的大内存分配。
  • 虚构API——调用导入模块中不存在的函数/方法（在AI生成的PR中尤为常见）。如有疑问，通过工作树
    Read
    导入模块进行验证。
  • 遗留内容——TODO注释、调试日志、
    console.log
    、被注释的代码、死分支。
如果某个类别确实无问题，用一句话说明（如“测试：覆盖全面，对新增分支进行了断言。”）。如果所有项都无问题，用一句话总结。

Length and tone

篇幅与语气

  • One paragraph per file for typical changes. Expand to several for non-trivial logic. Collapse trivial files (lockfiles, snapshots, mass renames, generated code) into a single grouped paragraph.
  • The user already has the diff — don't paste large hunks back. Quote specific lines only when calling something out, and prefer a line-anchored link over a quoted block when the link alone is enough.
  • Plain prose with markdown structure.
  • 对于典型变更，每个文件用一段文字说明。对于复杂逻辑，可扩展为多段。将无关紧要的文件（锁文件、快照、批量重命名、生成代码）合并为一段说明。
  • 用户已拥有差异内容——请勿粘贴大段差异。仅在需要标注时引用特定代码行，且当链接足够清晰时，优先使用行锚定链接而非引用块。
  • 使用简洁的 prose 配合markdown结构。

Footer

页脚

End the review with a one-line cleanup hint:
Worktree at 
.pr-review/<branch-slug>/
(PR head 
<sha>
). Saved review: 
.pr-review/<branch-slug>/WALKTHROUGH.md
— share this file as-is. To remove the worktree now: 
git worktree remove --force .pr-review/<branch-slug>
. Other branches' worktrees under 
.pr-review/
are untouched — list them with 
git worktree list
.
Substitute the real branch slug and SHA in the actual output.
在审查报告末尾添加一行清理提示：
工作树位于
.pr-review/<branch-slug>/
（PR头部SHA为
<sha>
）。已保存的审查报告：
.pr-review/<branch-slug>/WALKTHROUGH.md
——可直接共享该文件。如需立即移除工作树：执行
git worktree remove --force .pr-review/<branch-slug>
。
.pr-review/
下其他分支的工作树不受影响——可通过
git worktree list
查看。
在实际输出中替换为真实的分支slug和SHA值。