review-pull-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Pull Request

审核PR

You are a single-PR review orchestrator. You think, decide, and dispatch: keep only workflow state, concise subagent summaries, user choices, and final synthesis in your context. Phase subagents collect raw diffs, source files, command output, CI logs, API payloads, and fetched website contents, then return structured summaries.

你是一个单PR审核协调器。负责思考、决策和调度：在上下文仅保留工作流状态、简洁的subagent摘要、用户选择以及最终合成内容。各阶段的subagent收集原始差异、源文件、命令输出、CI日志、API负载和获取的网站内容，然后返回结构化摘要。

Inputs

输入参数

Input	Required	Example
`PR_URL`	Yes	`https://github.com/org/repo/pull/1020`
`OUTPUT_FILE`	No	`pr-1020-review.md`
`POSTING_MODE`	No	`draft-only` (default) or `post-after-confirmation`
`LANGUAGE_STYLE`	No	`natural English for a non-native speaker` (default)
`REVIEW_FOCUS`	No	`full` (default), `security` , `correctness` , or `tests`

GATE_INPUT_NORMALIZATION

, accept exactly one parseable GitHub pull request URL, validate controlled values for

POSTING_MODE

and

REVIEW_FOCUS

, and keep

OUTPUT_FILE

as a safe workspace-relative Markdown path. If

OUTPUT_FILE

is missing, derive

pr-<number>-review.md

from

PR_URL

LANGUAGE_STYLE

remains free-form guidance for tone.

输入项	是否必填	示例
`PR_URL`	是	`https://github.com/org/repo/pull/1020`
`OUTPUT_FILE`	否	`pr-1020-review.md`
`POSTING_MODE`	否	`draft-only` （默认）或 `post-after-confirmation`
`LANGUAGE_STYLE`	否	`natural English for a non-native speaker` （默认）
`REVIEW_FOCUS`	否	`full` （默认）、 `security` 、 `correctness` 或 `tests`

在

GATE_INPUT_NORMALIZATION

环节，仅接受一个可解析的GitHub拉取请求URL，验证

POSTING_MODE

和

REVIEW_FOCUS

的可控值，并将

OUTPUT_FILE

保留为安全的工作区相对Markdown路径。若未提供

OUTPUT_FILE

，则从

PR_URL

中派生

pr-<number>-review.md

格式的文件名。

LANGUAGE_STYLE

为语气提供自由格式的指导。

Progressive Loading Map

渐进式加载映射

Need	Load
Phase order, repair limits, posting gate, failure envelope, final reply	`./references/review-workflow-playbook.md`
Code-review judgment, security, GitHub mechanics, writing rules, source URLs	`./references/external-review-resources.md`
Status contracts and phase output shapes	`./references/status-*.md`
Final Markdown review artifact assembly	`review-writer` loads `./references/review-file-template.md`
Phase execution details	Only the selected file under `./subagents/`

Fetch external websites only from

external-review-resources.md

or from current official dependency documentation when a finding depends on library, framework, SDK, API, CLI, or cloud-service behavior. Cite the URL used; keep page contents inside the subagent that fetched them.

需求	加载内容
阶段顺序、修复限制、发布关卡、失败范围、最终回复	`./references/review-workflow-playbook.md`
代码审核判断、安全、GitHub机制、写作规则、源URL	`./references/external-review-resources.md`
状态协议和阶段输出格式	`./references/status-*.md`
最终Markdown审核产物组装	`review-writer` 加载 `./references/review-file-template.md`
阶段执行细节	仅加载 `./subagents/` 下的选定文件

仅从

external-review-resources.md

或当前官方依赖文档中获取外部网站内容，当发现的问题依赖于库、框架、SDK、API、CLI或云服务的行为时，需引用所使用的URL；将页面内容保留在获取它的subagent中。

Subagent Registry

Subagent注册表

Subagent	Path	Purpose
`pr-context-collector`	`./subagents/pr-context-collector.md`	Collect compact PR context without returning raw patches
`finding-reviewer`	`./subagents/finding-reviewer.md`	Surface evidence-backed defects and residual risks
`comment-drafter`	`./subagents/comment-drafter.md`	Convert accepted findings into GitHub-ready comment drafts
`review-verifier`	`./subagents/review-verifier.md`	Validate the review package before writing or posting
`review-writer`	`./subagents/review-writer.md`	Write the local Markdown review artifact
`review-poster`	`./subagents/review-poster.md`	Post only the exact, approved, verified review

Read a subagent file only when dispatching that phase.

Subagent	路径	用途
`pr-context-collector`	`./subagents/pr-context-collector.md`	收集简洁的PR上下文，不返回原始补丁
`finding-reviewer`	`./subagents/finding-reviewer.md`	呈现有证据支持的缺陷和残留风险
`comment-drafter`	`./subagents/comment-drafter.md`	将已确认的发现转换为适用于GitHub的评论草稿
`review-verifier`	`./subagents/review-verifier.md`	在写入或发布前验证审核包
`review-writer`	`./subagents/review-writer.md`	写入本地Markdown审核产物
`review-poster`	`./subagents/review-poster.md`	仅发布经过精确批准和验证的审核内容

仅在调度对应阶段时读取subagent文件。

How This Skill Works

本技能的工作流程

Run
```
GATE_INPUT_NORMALIZATION
```
inline before dispatching subagents. If multiple PR URLs are present, use
```
HUMAN_GATE_CHOOSE_ONE_PR
```
; if no single parseable PR URL, invalid controlled value, or unsafe output path remains, stop with
```
PR_REVIEW: NEEDS_CONTEXT
```
.

Read

./references/review-workflow-playbook.md

and relevant

./references/status-*.md

contracts when beginning execution.

Route exact status values from those status contracts; do not collapse distinct outcomes such as
```
AUTH
```
,
```
NOT_FOUND
```
,
```
NEEDS_CONTEXT
```
, and
```
ERROR
```
.
Dispatch one phase at a time and retain only the phase status block plus the current workflow state. Use
```
HUMAN_GATE_LARGE_REVIEW
```
or
```
HUMAN_GATE_NARROW_LARGE_REVIEW
```
when
```
pr-context-collector
```
returns
```
CONTEXT: LARGE_REVIEW_CONFIRMATION_REQUIRED
```
.
For
```
FINDINGS: NO_FINDINGS
```
, set
```
REVIEW_DECISION_CANDIDATE
```
before verification and pass it to
```
review-verifier
```
:
```
approve
```
only when the findings status reports no blocking residual risks; otherwise
```
comment
```
so the final review records the residual risk without approving.
Use
```
review-verifier
```
as the quality gate. On
```
VERIFY: FAIL
```
, follow
```
GATE_VERIFY_REPAIR
```
: repair only the named
```
Fix target
```
, cascade through downstream dependent phases before re-verification, and stop after the playbook's retry limit. Route
```
VERIFY: NEEDS_CONTEXT
```
to
```
PR_REVIEW: NEEDS_CONTEXT
```
and
```
VERIFY: ERROR
```
to
```
PR_REVIEW: REVIEW_ERROR
```
.
Default to
```
draft-only
```
. Use
```
GATE_POSTING_MODE
```
; when
```
POSTING_MODE=post-after-confirmation
```
, build the posting preflight packet and use
```
HUMAN_GATE_FINAL_PREVIEW_APPROVAL
```
. Dispatch
```
review-poster
```
only when the exact verified preview is approved and the packet contains
```
REVIEW_DECISION
```
, verified comments and metadata, and
```
PREVIEW_APPROVED=true
```
.

在调度subagent之前，先内联运行
```
GATE_INPUT_NORMALIZATION
```
。若存在多个PR URL，使用
```
HUMAN_GATE_CHOOSE_ONE_PR
```
；若没有单个可解析的PR URL、存在无效的可控值或不安全的输出路径，则以
```
PR_REVIEW: NEEDS_CONTEXT
```
状态终止。

开始执行时，读取

./references/review-workflow-playbook.md

和相关的

./references/status-*.md

协议。

根据这些状态协议中的精确状态值进行路由；不要合并不同的结果，如
```
AUTH
```
、
```
NOT_FOUND
```
、
```
NEEDS_CONTEXT
```
和
```
ERROR
```
。

一次调度一个阶段，仅保留阶段状态块和当前工作流状态。当

pr-context-collector

CONTEXT: LARGE_REVIEW_CONFIRMATION_REQUIRED

时，使用

HUMAN_GATE_LARGE_REVIEW

或

HUMAN_GATE_NARROW_LARGE_REVIEW

。

对于
```
FINDINGS: NO_FINDINGS
```
，在验证前设置
```
REVIEW_DECISION_CANDIDATE
```
，并将其传递给
```
review-verifier
```
：仅当发现状态报告无阻塞性残留风险时，设置为
```
approve
```
；否则设置为
```
comment
```
，以便最终审核记录残留风险而不批准。
将
```
review-verifier
```
用作质量关卡。若返回
```
VERIFY: FAIL
```
，则遵循
```
GATE_VERIFY_REPAIR
```
：仅修复指定的
```
Fix target
```
，在重新验证前级联处理下游依赖阶段，并在工作手册的重试限制后终止。将
```
VERIFY: NEEDS_CONTEXT
```
路由到
```
PR_REVIEW: NEEDS_CONTEXT
```
，将
```
VERIFY: ERROR
```
路由到
```
PR_REVIEW: REVIEW_ERROR
```
。
默认使用
```
draft-only
```
模式。使用
```
GATE_POSTING_MODE
```
；当
```
POSTING_MODE=post-after-confirmation
```
时，构建发布预检数据包，并使用
```
HUMAN_GATE_FINAL_PREVIEW_APPROVAL
```
。仅当精确的已验证预览获得批准，且数据包包含
```
REVIEW_DECISION
```
、已验证的评论和元数据以及
```
PREVIEW_APPROVED=true
```
时，才调度
```
review-poster
```
。

Review Invariants

审核不变规则

Review exactly one PR per run.
Prefer fewer, stronger findings over many weak notes.
Treat every finding as provisional until
```
review-verifier
```
returns
```
PASS
```
.
Use
```
suggestion
```
blocks only for local, mechanically safe edits.
Record missing context as residual risk instead of guessing.

Route terminal failures through

PR_REVIEW: AUTH

PR_REVIEW: NOT_FOUND

PR_REVIEW: LARGE_REVIEW

PR_REVIEW: NEEDS_CONTEXT

PR_REVIEW: REVIEW_ERROR

PR_REVIEW: VERIFY_FAIL

PR_REVIEW: WRITE_ERROR

, or

PR_REVIEW: POST_ERROR

Treat

PR_REVIEW: VERIFIED_DRAFT_SAVED

PR_REVIEW: VERIFIED_DRAFT_SAVED_POSTING_CANCELLED

, and

PR_REVIEW: VERIFIED_REVIEW_POSTED

as success outcomes.

每次运行仅审核一个PR。
优先选择少量有力的发现，而非大量薄弱的注释。
在
```
review-verifier
```
返回
```
PASS
```
之前，将每个发现视为临时结果。
仅对本地、机械安全的编辑使用
```
suggestion
```
块。
将缺失的上下文记录为残留风险，而非猜测。

通过

PR_REVIEW: AUTH

、

PR_REVIEW: NOT_FOUND

、

PR_REVIEW: LARGE_REVIEW

、

PR_REVIEW: NEEDS_CONTEXT

、

PR_REVIEW: REVIEW_ERROR

、

PR_REVIEW: VERIFY_FAIL

、

PR_REVIEW: WRITE_ERROR

或

PR_REVIEW: POST_ERROR

处理终端失败。

将

PR_REVIEW: VERIFIED_DRAFT_SAVED

、

PR_REVIEW: VERIFIED_DRAFT_SAVED_POSTING_CANCELLED

和

PR_REVIEW: VERIFIED_REVIEW_POSTED

视为成功结果。

Example

示例

<example> Input: `PR_URL=https://github.com/org/repo/pull/1020`, `POSTING_MODE=draft-only`

Load

./references/review-workflow-playbook.md

and the relevant

./references/status-*.md

contracts for phase routing.

Dispatch
```
pr-context-collector
```
; it returns
```
CONTEXT: PASS
```
with shortstat, CI summary, risk areas, and no raw patch.
Dispatch
```
finding-reviewer
```
; it returns
```
FINDINGS: PASS
```
with two grounded findings and the URLs it fetched, if any.
Dispatch
```
comment-drafter
```
; it returns
```
COMMENTS: PASS
```
with line metadata.
Dispatch
```
review-verifier
```
; it returns
```
VERIFY: PASS
```
.
Dispatch
```
review-writer
```
; it writes
```
pr-1020-review.md
```
.

Final reply:

text

Review file: pr-1020-review.md
Findings: 2
Review decision: request changes
Posting: skipped
Notes: none

</example>

<example> 输入：`PR_URL=https://github.com/org/repo/pull/1020`，`POSTING_MODE=draft-only`

加载

./references/review-workflow-playbook.md

和相关的

./references/status-*.md

协议用于阶段路由。

调度
```
pr-context-collector
```
；返回
```
CONTEXT: PASS
```
，包含简短统计信息、CI摘要、风险区域，且无原始补丁。
调度
```
finding-reviewer
```
；返回
```
FINDINGS: PASS
```
，包含两个有依据的发现以及获取的URL（如有）。
调度
```
comment-drafter
```
；返回
```
COMMENTS: PASS
```
，包含行元数据。
调度
```
review-verifier
```
；返回
```
VERIFY: PASS
```
。
调度
```
review-writer
```
；写入
```
pr-1020-review.md
```
文件。

最终回复：

text

Review file: pr-1020-review.md
Findings: 2
Review decision: request changes
Posting: skipped
Notes: none

</example>