agentleFS
fitlab-aifitlab-ai/agent-infra/.agents/skills/review-pr/SKILL.md

review-pr

Skill88 starsChanged 21 days agoMITView on GitHub

按证据分级审查 PR 并发布正式 Review。 当需要审查一个 PR(无论是否已有可信生命周期记录)时使用。 仅当对话包含可解析的 PR 编号或 PR URL 时才可自动调用本技能。

185 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use diagnose-ci-failures, review-delta and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • zerx-labSkill

    diagnose-ci-failures

    Diagnose CI failures for a PR using the GitHub CLI, extract error logs, and generate a plan to fix them. Use when the user asks to check CI status, pull CI issues, triage test failures, or investigate PR build failures.

    Also in 3 projects that use this

  • n24q02mSkill

    review-delta

    Review only changes since last commit using impact analysis. Token-efficient delta review with automatic blast-radius detection.

    Also in 3 projects that use this

  • GeiserXSkill

    docs-loop

    Use when the user asks to audit docs, check documentation for stale claims, or verify docs against the code.

    Also in 3 projects that use this

  • GeiserXSkill

    full-loop

    Drive a repository to done with sergio-loop, then keep improving it with refine-loop at a descending theta. Use only when the user explicitly invokes full-loop.

    Also in 3 projects that use this

  • n24q02mSkill

    build-graph

    Build or update the code review knowledge graph. Run this first to initialize, or let hooks keep it updated automatically.

    Also in 3 projects that use this

  • +7 more from GeiserX

The file

Files
SKILL.md

审查 PR

根据目标 PR 的生命周期证据完整度与变更风险,选择 verify(轻量复核)、audit(证据审计)或 reconstruct(重建式审查),并把可执行的检视结论作为正式 PR Review 发布到目标 PR,同时保留可追溯的审查过程证据(pr-review.md / pr-review-r{N}.md)。

行为边界 / 关键规则

持久化报告证据

生成 PR 审查报告时,先读取 .agents/rules/evidence-reporting.md。正常审查记录命令、范围、结构化结果、实际结论和未覆盖部分;正式 Review、finding、阻塞或争议的身份字段和决定性证据必须精确保留。

  • 严格遵循方案中固化的证据分级主决策流:宿主解析 → 证据分类 → 新鲜度/对齐 → 风险分级 → 模式选择
  • pr-review* 是独立 artifact family:不接入 analysis/plan/code 阶段依赖链,不修改 current_step
  • PR 上只发布正式 PR Review(head SHA、结论、finding、receipt、Issue artifact 链接),不发第二份完整过程原文到 PR 普通评论
  • 完整过程原文与 task.md 的可逆镜像只在关联 Issue 上同步;restore-task 保持 Issue-only 契约
  • 生成会同步到 Issue 的 artifact Markdown 前,先读取 .agents/rules/sync-content-generation.md 并遵循其中的生成端约束;Issue 同步保持透明,不解析或改写正文
  • 不得为外部 PR 倒填或伪造已发生的 analysis/plan/code 生命周期历史
  • head SHA 唯一记录于 pr-review* 与正式 PR Review;head 漂移必须进入新轮次,不得沿用旧结论
  • 审查深度由证据完整度和变更风险决定,不由提交者身份决定
  • 执行本技能后,你必须立即更新 task.md(经 task-activity typed intent)
  • 绝不自动执行 git add 或 git commit
  • 一次性检视路径(无任务/Issue)走 <task-workspace>/reviews/{pr-number}/,标记 recoverable: false,不承担可恢复承诺

常见违规借口与反驳

借口反驳
「代码 diff 直接看就行了,不需要重建上下文」仅看 diff 会遗漏需求边界、架构选择与迁移策略;reconstruct 必须先产出最低充分重建记录。
「PR 没有关联任务,直接写个报告发出去」默认阻塞并要求先关联 Issue/task;只有显式「仅一次性检视」才走不可恢复降级路径。
「把完整重建过程也发到 PR 普通评论,方便贡献者看」过程原文只同步到 Issue artifact 评论;PR 只保留正式 Review,避免重复远端副本与恢复源混淆。
「审查完了顺手提交一下」本技能绝不执行 git add/git commit;提交是用户显式发起的独立步骤。

第 0 步:状态核对(执行前硬约束)

在加载本技能与相关规则后、做任何任务状态判断或用户可见结论之前,必须先执行状态核对:

agent-infra-internal task-snapshot {task-id} --format text

任务锚定路径在开始前记录当前任务目录与既有 pr-review* 轮次;一次性路径(无任务)记录 PR 编号与目标目录。将命令、PR/head、审查范围、关键结果和未覆盖部分写入本轮产物 pr-review-rN.md 的 ## 状态核对 段;正常成功不粘贴完整目录清单或 task.md 尾部,身份不一致、失败、阻塞或争议时保留决定性原文行。

执行步骤

1. 解析入参与宿主解析

解析目标 PR 编号 {pr-number}(--pr <number>,或 PR URL,或省略时按当前分支反查)。执行:

agent-infra-internal platform-pr-review inspect --pr {pr-number} [--cwd <path>]
agent-infra-internal pr-review-grade resolve-host --pr {pr-number} [--cwd <path>]

resolve-host 输出 HostResolution(unique / ambiguous / none),按以下策略分流:

  • 唯一宿主:绑定 {task-id},调用 task-activity pr-review-inspect 取得 canonical round、prepared/open 状态和最近成功审查身份,再按下述恢复规则开始本轮(进入步骤 2)。
  • 多宿主歧义:resolve-host 返回 ambiguous,decide 会拒绝分类(fail closed)。立即停止并提示人工指定唯一宿主;不进入证据分类。
  • 无宿主:默认阻塞,要求先建立 Issue/task 关联(给出关联指引),不自动创建/导入 Issue。仅当用户显式选择「仅一次性检视」时,过程文件写入 <task-workspace>/reviews/{pr-number}/(recoverable: false)。

任务锚定路径在宿主与远端 head 确定后执行:

agent-infra-internal task-activity {task-id} pr-review-inspect
  • prepared:复用该 artifact;open 且 head 未变:对同一 artifact/head 重放 start(no-op)并恢复该轮。
  • open 且 head 已变:先把旧 artifact 的正式 Review 状态写为 superseded,再用旧 artifact/head 执行 terminate;随后使用 inspect 返回的 next round。
  • 无 prepared/open:按 reference/report-template.md 创建 next artifact 骨架,先写状态核对、身份信息、被审 head 与 正式 Review 状态: pending。

在上述分流完成后、步骤 2 证据分级开始前写 started:

agent-infra-internal task-activity {task-id} pr-review-start --agent {agent} \
  --artifact {pr-review-artifact} --head {head-sha}

一次性路径不调用 task-activity。读取 PR、确定 head 或本地审查失败时,先把 artifact 状态写为 aborted,再以同一 artifact/head 调用 pr-review-terminate --outcome aborted --reason <single-line>。本地审查结论完成后的发布失败记录恢复事实,不将审查轮次误判为 aborted。

2. 单次 decide:证据枚举 + 场景分类 + 风险分级 + 模式选择

把宿主、artifact 存在性、head 状态与六个纯证据风险因素写入输入 JSON。prior review 只使用 inspect 返回的最高 applied / no-op artifact;pending/aborted/superseded/failed 只参与 round 连续性,不作为既有结论。调用一次:

agent-infra-internal pr-review-grade decide --input-file {decide-input.json} [--cwd <path>]

一次返回完整 DecisionRecord(scenario / freshness / alignment / risk / mode / firstReview / reason)。把决策输入与输出原样记录到 pr-review-rN.md 的「证据清单」段(AC3 可追溯)。host.kind === 'ambiguous' 时命令拒绝,回到步骤 1 的阻塞出口。

3. 生成 pr-review-rN.md

按 reference/report-template.md 完成本轮产物;任务锚定路径保留步骤 1 已写入的身份/head/pending 状态,不重新分配 round。reconstruct(或 audit 证据不足)时,在行级 finding 之前先写「重建上下文」段(需求边界 / 架构选择 / 影响面 / 验证覆盖,见 reference/evidence-grading.md)。frontmatter 或首部记录 recoverable: true|false(一次性路径为 false)。完成最终问题清单后,一次性冻结 {verdict, blockers, major, minor};正式 Review 正文与步骤 6 的 complete payload 必须直接复用该对象,不从报告文案反向统计。

4. 同步 Issue artifact 评论(任务锚定路径)

依次尝试同步 task 评论与 artifact 评论;失败时记录 warning 和恢复事实,继续本地审查:

agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}
agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {pr-review-artifact} --agent {agent}

一次性路径(无任务/Issue)跳过本步。

5. 核对 head 并发布正式 Review

再次读取远端 head,确认未被审查期间漂移:

agent-infra-internal platform-pr-review inspect --pr {pr-number} [--cwd <path>]

若 head 与步骤 1 记录一致,组装正文(head SHA / 结论 / finding / receipt / 已取得的 Issue artifact 链接;评论待恢复时写明 artifact 身份,不含 marker)。把完整正文写入与本轮报告同目录的 pr-review-body.md(Round 1)或 pr-review-body-r{N}.md(后续轮次),并将 {review-body-file} 绑定为该文件的绝对路径。本轮报告的「正式 Review 正文」段只记录该文件名。任务锚定路径必须使用任务目录中的该文件;失败恢复会按报告轮次重读该文件并核对正文摘要。然后发布正式 Review:

agent-infra-internal platform-pr-review publish --pr {pr-number} --scope {taskId|pr{pr-number}} --round {round} \
  --commit {head-sha} --event {COMMENT|APPROVE|REQUEST_CHANGES} --body-file {review-body-file} --artifact {pr-review-artifact} --agent {agent} [--dry-run] [--cwd <path>]

publish 由 core 生成并校验 marker(首行),按 marker + commit 幂等(重放 no-op;marker 命中但 commit 不一致稳定失败)。head 漂移时,先把旧 artifact 状态写为 superseded,再闭合旧轮:

agent-infra-internal task-activity {task-id} pr-review-terminate --agent {agent} \
  --artifact {pr-review-artifact} --head {head-sha} \
  --outcome superseded --reason "head changed before publish"

闭合成功后重新执行步骤 1,进入下一 canonical round;不得先写新轮 started。publish 结果不确定且已有任务账本记录时,保留待恢复操作并继续本地审查轮次;无法证明恢复事实已持久化时保持 open。

6. 回写发布结果与任务状态

  • 任务锚定路径:把 publish 的实际状态写入 pr-review-rN.md「发布结果」段。applied / no-op 时记录 Review ID/URL;写入失败且已有任务账本记录时写 blocked / failed、错误码和恢复动作。随后以步骤 3 冻结的同一组 verdict/counts 闭合本地审查状态:

    agent-infra-internal task-activity {task-id} pr-review-complete --agent {agent} \
      --artifact {pr-review-artifact} --head {head-sha} --verdict {approved|changes-requested|commented} \
      --blockers {blockers} --major {major} --minor {minor}

    task-activity 由 typed payload 生成 Verdict: <结论>, blockers: N, major: N, minor: N → {pr-review-artifact},并经 writeTask 原子完成结构化审查状态、## 审查反馈 链接与版本戳刷新;日志可安全追加时一并写入,否则返回诊断;不改 current_step,也不把 receipt/head/Review URL 写入 NOTE。

  • 一次性路径(无任务):把实际发布状态写入 pr-review-rN.md「发布结果」段;成功时记录 Review ID/URL,失败时记录错误与不可自动恢复的限制。不调用 task-activity。

7. 发布后回写再同步(任务锚定路径)

步骤 6 已改写本地 pr-review-rN.md「发布结果」段与 task.md(审查状态及可用日志),而步骤 4 同步的是旧快照。依次尝试再同步;失败记录 warning,由 complete-task 在归档前补齐:

agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}
agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {pr-review-artifact} --agent {agent}

platform-comment sync 对既有 marker 评论是幂等原地更新,comment URL 不变。一次性路径无任务,跳过本步。

8. 完成校验

  • 任务锚定路径:

    agent-infra-internal task-verify {task-id} review-pr.completed --artifact {pr-review-artifact} --format text

按 .agents/rules/validation-output.md 展示当次校验摘要;失败、阻塞和软警告保留必要诊断。

  • 一次性路径:

    agent-infra-internal pr-review-grade verify-artifact --artifact-file {pr-review-artifact} [--cwd <path>]

退出码 0 通过;1 按输出修复后重跑;2(阻塞)保留阻塞状态并检查当次摘要。不得把未完成的 PR 审查或正式 Review 写入报告为完成;只继续独立的本地审查工作,必要的授权或缺失事实才交由用户提供。

9. 告知用户

按 reference/output-guidance.md 选择唯一出口(本地审查完成 / 阻塞要求关联 / 一次性检视),渲染下一步前读取 .agents/rules/next-step-output.md。

完成检查清单

  • 已按证据分级完成 PR 审查并产出 pr-review-rN.md
  • 正式 Review 已发布、任务账本已记录待恢复操作,或一次性路径已如实记录发布失败
  • 任务锚定路径的 Issue artifact/task 评论已同步,或失败已记录待恢复
  • 已完成校验(task-verify 或 verify-artifact)
  • 已更新 task.md 中的审查状态并记录日志诊断(如适用)

停止

完成检查清单后立即停止。不要自动提交。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.