github-deep-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Deep Review

GitHub 深度审查

Review like Peter: high-confidence, evidence-first, code-aware, and willing to say "not proven" when the trail is weak. The goal is not a generic summary. The goal is to understand the bug class, find the real cause if possible, decide the best fix after reading enough code, and call out whether a larger refactor would improve the design.

像Peter一样审查：高可信度、证据优先、具备代码感知能力，当线索不足时敢于说「证据不足」。目标不是生成泛泛的总结，而是要理解Bug类型，尽可能找到根本原因，在阅读足够代码后确定最优修复方案，并指出更大规模的重构是否能改进设计。

Start

开始

Use

gh

, not web browsing, for GitHub refs:

bash

gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch

For PRs, collect author context by default unless the author is Peter (

steipete

or an obvious Peter-owned account). Use the local workflow in

~/Projects/agent-scripts/skills/github-author-context/SKILL.md

and include a short

Author context:

block near the top of the review when the author is not Peter. After merge/rejection/close/review, use that same author-context workflow to append a contributor note only when the interaction creates durable future-review signal.

For repo-local review, also inspect:

bash

git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"

If the repo has local instructions, issue/PR skills, docs lists, test guidance, or maintainer runbooks, read those before deciding.

对于GitHub引用，请使用

gh

而非网页浏览：

bash

gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch

对于PR，默认收集作者上下文，除非作者是Peter（

steipete

或明显属于Peter的账号）。当作者不是Peter时，使用

~/Projects/agent-scripts/skills/github-author-context/SKILL.md

中的本地工作流，并在审查顶部附近添加简短的

Author context:

块。在合并/驳回/关闭/审查完成后，仅当此次交互产生了对未来审查有长期价值的信号时，使用相同的作者上下文工作流追加贡献者备注。

对于本地仓库审查，还需检查：

bash

git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"

如果仓库有本地说明、issue/PR相关技能、文档列表、测试指南或维护者操作手册，请先阅读这些内容再做判断。

Review Contract

审查必答项

Always answer these, explicitly:

URL/ref: issue or PR number and affected surface.
What is the bug or behavior being fixed?
Can we identify the root cause? If yes, where in code and why. If no, what evidence is missing.
For regressions, who/what introduced it and when? Include commit/PR provenance when traceable by bounded history; say unknown instead of guessing.
Is the current/proposed fix the best possible fix after reading adjacent code?
Would a bigger refactor improve correctness, clarity, or future maintainability?
What proof exists: tests, live repro, CI checks, docs, dependency docs/source, shipped/current behavior.
What remains risky or unverified.

必须明确回答以下问题：

URL/引用：issue或PR编号以及受影响的范围。
正在修复的Bug或行为是什么？
我们能否确定根本原因？如果能，指出代码中的位置及原因；如果不能，说明缺少哪些证据。
对于回归问题，是谁/什么引入的、何时引入的？如果通过有限历史可追溯，需包含commit/PR的来源；不要猜测，不确定就说未知。
在阅读了周边代码后，当前/提议的修复方案是否是最优解？
更大规模的重构是否能提升正确性、清晰度或未来可维护性？
现有证据：测试、线上复现、CI检查、文档、依赖文档/源码、已发布/当前行为。
仍存在哪些风险或未验证的内容。

Code Reading Depth

代码阅读深度

Read past the first touched file. Follow the real call path:

entrypoint -> validation/parsing -> routing/dispatch -> owner module -> shared helper -> persistence/network/runtime boundary
config/schema/docs -> runtime usage -> doctor/migration/fix path
provider/channel/plugin owner code -> generic core seam, only if multiple owners need it
tests around the touched surface plus adjacent regression tests

When behavior depends on a dependency, read the upstream docs/source/types or current package contract before assuming.

Prefer current source and executable proof over issue comments. Treat stale comments, old CI, and old release behavior as hints until rechecked.

不要只停留在第一个被修改的文件，要追踪真实的调用路径：

入口点 -> 校验/解析 -> 路由/分发 -> 所属模块 -> 共享工具类 -> 持久化/网络/运行时边界
配置/schema/文档 -> 运行时使用 -> doctor/迁移/修复路径
提供者/通道/插件所属代码 -> 通用核心接缝（仅当多个所有者需要时才查看）
被修改范围周边的测试，以及相关的回归测试

当行为依赖于某个依赖项时，在假设之前请先阅读上游文档/源码/类型定义或当前包的约定。

优先采信当前源码和可执行的证据，而非issue评论。在重新验证之前，将过时的评论、旧的CI结果和旧版本的行为仅作为参考提示。

Provenance

溯源

For bug/regression reviews, include a compact

Provenance:

answer when feasible:

Use
```
git log -S/-G
```
,
```
git blame
```
, and linked PRs/issues to locate candidates, not prove introduction. Before saying
```
introduced by
```
, inspect raw parents with
```
git --no-replace-objects cat-file -p <sha>
```
and verify that
```
git --no-replace-objects diff --no-ext-diff --no-textconv <raw-parent> <sha> -- <path>
```
changed the implicated behavior, using tests/repro when feasible. A genuine root needs raw-header proof that it has no parents.
Blame
```
^sha
```
, porcelain
```
boundary
```
, and shallow/grafted history alone are not introduction proof.
```
--root
```
can hide boundary markers;
```
git show
```
and
```
rev-list --parents
```
can disguise a shallow boundary as a root. An available raw parent permits explicit comparison even at a shallow boundary; missing parents or an unverifiable patch require
```
unknown
```
with the gap, not inference from a subject, date, or author.
Separate code author, introducing PR author, merger, committer, automation trigger, and current PR author. Verify identities and triggers from explicit metadata/events; a role is not proof of causation, and an unverified identity stays unknown.
Use
```
made visible by
```
only for a verified trigger and
```
carried forward by
```
only for verified preexisting behavior. Apply the same evidence bar to summaries and owner hints, not just a
```
Provenance:
```
field. Include confidence:
```
clear
```
,
```
likely
```
, or
```
unknown
```
.
For features, docs, and refactors, write
```
N/A
```
; for untraceable bugs, report
```
unknown
```
with the missing evidence. Missing provenance does not invalidate an independently proven bug.

对于Bug/回归审查，在可行的情况下包含一个简洁的

Provenance:

回答：

使用
```
git log -S/-G
```
、
```
git blame
```
和关联的PR/issue来定位候选提交，而非直接证明引入来源。在说「由...引入」之前，需用
```
git --no-replace-objects cat-file -p <sha>
```
检查原始父提交，并通过
```
git --no-replace-objects diff --no-ext-diff --no-textconv <raw-parent> <sha> -- <path>
```
验证相关行为确实发生了变化，可行的话使用测试/复现来验证。真正的根提交需要有原始头部证明其没有父提交。
仅靠Blame的
```
^sha
```
、porcelain格式的
```
boundary
```
以及浅克隆/嫁接历史都不能作为引入的证据。
```
--root
```
可能会隐藏边界标记；
```
git show
```
和
```
rev-list --parents
```
可能会将浅克隆边界伪装成根提交。即使在浅克隆边界下，只要有可用的原始父提交，就可以进行明确比较；如果缺少父提交或补丁无法验证，则需标记为
```
unknown
```
并说明缺失的信息，不要根据提交主题、日期或作者进行推断。
区分代码作者、引入PR的作者、合并者、提交者、自动化触发者和当前PR作者。需通过明确的元数据/事件验证身份和触发原因；角色不能作为因果关系的证据，未验证的身份保持为未知。
仅对已验证的触发因素使用
```
made visible by
```
（由...暴露），仅对已验证的预先存在的行为使用
```
carried forward by
```
（由...延续）。对总结和所有者提示也应采用相同的证据标准，而不仅仅是
```
Provenance:
```
字段。需包含可信度：
```
clear
```
（明确）、
```
likely
```
（可能）或
```
unknown
```
（未知）。
对于功能、文档和重构，填写
```
N/A
```
；对于无法追溯的Bug，报告
```
unknown
```
并说明缺失的证据。缺少溯源信息并不会使独立验证的Bug失效。

Fix Quality Bar

修复质量标准

Good fixes usually:

live at the ownership boundary where the bug belongs
preserve public/backward-compatible behavior unless the issue is about retiring it
add a regression test at the smallest meaningful seam
avoid broad special cases, hidden migrations, semantic sentinels, and provider/channel IDs in generic core
update docs/changelog when user-visible behavior changes
fail clearly in runtime paths and repair through doctor/migration paths when that is the established contract

Call out when a fix is only symptom-level. If a slightly larger refactor makes the invariant obvious and reduces future bugs, recommend it. If the refactor widens risk without improving the bug class, say so.

好的修复通常具备以下特点：

位于Bug所属的权责边界处
保留公共/向后兼容行为，除非该issue就是要废弃该行为
在最小的有意义的接缝处添加回归测试
避免在通用核心中添加宽泛的特殊情况、隐藏的迁移、语义标记以及提供者/通道ID
当用户可见的行为发生变化时，更新文档/变更日志
运行时路径中出现明确失败时，若已有约定则通过doctor/迁移路径进行修复

如果修复只是治标不治本，要明确指出来。如果稍大规模的重构能让不变量更清晰并减少未来的Bug，就推荐重构。如果重构扩大了风险却没有改进Bug类型，也要如实说明。

PR Review Shape

PR审查结构

Lead with findings when reviewing a PR. Findings need file/line/symbol references and a concrete failure mode. Avoid vague "consider" comments.

If no blocking issues:

say no blocking correctness issues found
list the strongest proof checked
name residual risk/test gaps
answer whether the design is the best available shape

Do not approve, comment, close, merge, push, or land unless the user asked for that action.

审查PR时，先给出审查结论。结论需要包含文件/行号/符号引用以及具体的失败模式。避免模糊的「建议考虑」类评论。

如果没有阻塞性问题：

说明未发现阻塞性的正确性问题
列出已验证的最有力证据
指出剩余风险/测试缺口
回答当前设计是否是最优的可行方案

除非用户要求，否则不要执行批准、评论、关闭、合并、推送或上线操作。

Issue Review Shape

Issue审查结构

For bugs/issues:

Reconstruct the reporter's scenario and affected version/surface.
Check whether current
```
main
```
already fixes it.
Reproduce or create a minimal local/live proof when feasible.
If clear, identify root cause and proposed fix.
If solved on
```
main
```
, only comment/close when the user asks; include proof and the canonical commit/PR if known.

If reproduction is not feasible, say exactly what blocks it and what evidence would make the decision reliable.

对于Bug/issue：

重现报告者的场景以及受影响的版本/范围。
检查当前
```
main
```
分支是否已经修复了该问题。
可行的话，复现或创建最小化的本地/线上证据。
如果问题明确，确定根本原因并提出修复方案。
如果
```
main
```
分支已解决，仅在用户要求时才评论/关闭；如果已知的话，需包含证据和对应的标准commit/PR。

如果无法复现，要明确说明阻碍复现的原因，以及需要哪些证据才能做出可靠判断。

Output Template

输出模板

Use this shape when the user asks "what is this about", "is this the best fix", or "what did we fix":

text

Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>

Bug: <one or two sentences>
Cause: <code path + confidence>
Provenance: <introduced/made visible/carried forward by commit/PR/date, or N/A/unknown>
Best fix: <what should change and why>
Refactor: <yes/no, specific shape>
Proof: <tests/live/CI/source/dependency docs>
Risk: <remaining uncertainty>

Keep it concise, but do not skip the cause/fix/refactor/proof decision.

当用户询问「这是关于什么的」、「这是不是最优修复」或「我们修复了什么」时，使用以下结构：

text

Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>

Bug: <one or two sentences>
Cause: <code path + confidence>
Provenance: <introduced/made visible/carried forward by commit/PR/date, or N/A/unknown>
Best fix: <what should change and why>
Refactor: <yes/no, specific shape>
Proof: <tests/live/CI/source/dependency docs>
Risk: <remaining uncertainty>

保持简洁，但不要跳过原因/修复/重构/证据的判断。