piv-review-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review PR: The Agentic Gate Before the Human

审核PR：人工审核前的智能Agent关卡

Input: $ARGUMENTS

The point of this skill is fresh eyes: it reviews the PR in a clean context — not the context that wrote the code — and can hand the deep analysis to the code-reviewer
agent, which is the whole reason the review catches what the author's own context rationalizes away. It posts its verdict on the PR, then a human makes the final call.

输入：$ARGUMENTS

本Skill的核心是全新视角：它在干净的环境中审核PR——而非编写代码时的环境——并可将深度分析任务交给**

code-reviewer

Agent**，这正是该审核能发现代码作者因自身思维惯性而忽略问题的关键原因。它会将审核结论发布到PR上，最终由人工做出决定。

Phase 1 — Fetch the PR

第一阶段——获取PR

Resolve the input to a PR number (a number, a URL, or a branch via

gh pr list --head <branch> --json number -q '.[0].number'

). Then:

bash

gh pr view {N} --json number,title,body,author,headRefName,baseRefName,state,additions,deletions,changedFiles,files
gh pr diff {N}
gh pr checkout {N}

State guard:

MERGED

CLOSED

→ stop ("nothing to review");

DRAFT

→ review direction, don't approve/block.

将输入解析为PR编号（数字、URL或通过

gh pr list --head <branch> --json number -q '.[0].number'

获取的分支）。然后执行：

bash

gh pr view {N} --json number,title,body,author,headRefName,baseRefName,state,additions,deletions,changedFiles,files
gh pr diff {N}
gh pr checkout {N}

状态校验：若PR为

MERGED

CLOSED

状态则停止（“无内容可审核”）；若为

DRAFT

状态则仅给出审核方向，不进行批准/拦截操作。

Phase 2 — Load the context (so you review against the right bar)

第二阶段——加载上下文（确保审核标准正确）

CLAUDE.md
+ any
```
.claude/references/
```
— the project's standards are the review rubric.
The implementation report (if
```
piv-implement
```
wrote one —
```
.claude/reports/*{branch}*
```
) + its plan: read the documented deviations. A documented deviation is an intentional decision, not an issue — only flag undocumented divergences. (No report? Review normally and note its absence.)
The PR's own intent (title/body): what problem it claims to solve.

CLAUDE.md
及所有
```
.claude/references/
```
目录下的文件——项目标准即为审核准则。
实现报告（若
```
piv-implement
```
生成过报告，路径为
```
.claude/reports/*{branch}*
```
）及其计划：阅读已记录的偏差。已记录的偏差是有意的决策，不属于问题——仅标记未记录的偏离。（若无报告？按常规方式审核并注明报告缺失。）
PR自身的目标（标题/正文）：它声称要解决的问题。

Phase 3 — Run validation

第三阶段——运行验证

Run the project's real suite (the piv-validate
skill, or the plan's validation commands) — tests, type-check, lint, build. Capture pass/fail + counts. A red suite is a finding in itself.

运行项目的完整验证套件（piv-validate
Skill，或计划中的验证命令）——测试、类型检查、代码规范检查、构建。记录通过/失败状态及相关统计。验证不通过本身就是一个问题。

Phase 4 — Review the diff (dispatch the code-reviewer agent)

第四阶段——审核代码差异（调度code-reviewer Agent）

Hand the deep pass to a code-reviewer
subagent if the project has one (

.claude/agents/code-reviewer.md

); otherwise review in this session, in a clean context — it reviews against the project's standards and reports high-confidence issues only. Read every changed file in full (not just the diff) for context. Cover: correctness · type safety · pattern/standards compliance · security · performance · tests present · maintainability.

Categorize every issue by severity:

Severity	Meaning
Critical	Blocking — security, data loss, crashes
High	Should fix before merge — type-safety holes, missing error handling, logic errors
Medium	Pattern inconsistencies, missing edge cases, undocumented deviations
Low	Suggestions, minor polish

Acknowledge what's done well, too — review is constructive, not just a defect list.

若项目配置了**

code-reviewer

子Agent**（路径为

.claude/agents/code-reviewer.md

），则将深度审核任务交给它；否则在当前会话的干净环境中进行审核——审核需符合项目标准，仅报告高可信度问题。完整阅读每个变更文件（而非仅看差异）以获取上下文。审核范围包括：正确性 · 类型安全性 · 模式/标准合规性 · 安全性 · 性能 · 测试覆盖 · 可维护性。

按严重程度对每个问题分类：

严重程度	含义
Critical（严重）	阻塞性问题——安全漏洞、数据丢失、崩溃
High（高）	合并前需修复——类型安全漏洞、缺失错误处理、逻辑错误
Medium（中）	模式不一致、缺失边缘场景处理、未记录的偏差
Low（低）	建议、 minor polish（小优化）

同时也要认可做得好的部分——审核应具有建设性，而非仅列出缺陷。

Phase 5 — Decide

第五阶段——做出决策

Approve — no critical/high issues, validation passes, matches intent.
Request changes — high issues, or fixable validation failures, or undocumented pattern violations.
Block (request-changes, strongly) — critical security/data issues, or wrong fundamental approach.
Honor an explicit
```
--approve
```
/
```
--request-changes
```
flag, but never approve over an unresolved critical issue.

批准——无严重/高优先级问题，验证通过，符合PR目标。
要求修改——存在高优先级问题、可修复的验证失败，或未记录的模式违反情况。
拦截（强烈要求修改）——存在严重安全/数据问题，或基础方法错误。
若有明确的
```
--approve
```
/
```
--request-changes
```
标志则遵循，但绝不能批准存在未解决严重问题的PR。

Phase 6 — Post to GitHub + save the report

第六阶段——发布至GitHub + 保存报告

Write the report to

.claude/code-reviews/pr-{N}-review.md

(summary · issues by severity with

file:line

+ fix · validation table · what's good · recommendation). Then post it:

bash

undefined

将报告写入

.claude/code-reviews/pr-{N}-review.md

（内容包括：摘要 · 按严重程度分类的问题及

file:line

位置+修复建议 · 验证结果表 · 优点 · 推荐意见）。然后发布：

bash

undefined

approve

批准

gh pr review {N} --approve --body-file .claude/code-reviews/pr-{N}-review.md

request changes

要求修改

gh pr review {N} --request-changes --body-file .claude/code-reviews/pr-{N}-review.md

or just comment (draft PRs / advisory)

或仅评论（草稿PR/建议性审核）

gh pr comment {N} --body-file .claude/code-reviews/pr-{N}-review.md

undefined

gh pr comment {N} --body-file .claude/code-reviews/pr-{N}-review.md

undefined

Output + hand off

输出 + 交接

Print: PR number/URL · issue counts by severity · validation results · the recommendation. Then hand off: "Posted on the PR. A human now reviews the code + this review and merges." If there are issues, the natural next step is piv-fix-review-findings
on the report, then re-run validation.

打印：PR编号/URL · 各严重程度的问题数量 · 验证结果 · 推荐意见。然后交接：“已发布至PR。现在由人工审核代码及本审核报告并合并。” 若存在问题，下一步自然是针对报告执行**

piv-fix-review-findings

**，然后重新运行验证。

Notes

注意事项

Fresh eyes is the whole point — run this in a clean context (or let the
```
code-reviewer
```
agent be the clean context). Don't review with the session that wrote the code; it rationalizes instead of scrutinizing.
This is the agentic gate; it does not replace the human — it gives the human a validated, triaged PR to approve. Going deeper means multiple review agents, tuning the reviewer to your stack, and a validation pyramid behind it.

全新视角是核心——在干净环境中运行本Skill（或让
```
code-reviewer
```
Agent作为干净环境）。不要使用编写代码的会话进行审核；该会话会倾向于合理化问题而非仔细审查。
这是智能Agent关卡，并非替代人工——它为人工提供经过验证、分类的PR以供批准。更深入的方案包括使用多个审核Agent、针对技术栈调整审核规则，以及背后的验证金字塔体系。