Back to Details

iterate-pr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Iterate on PR Until CI Passes

迭代PR直至CI检查通过

Goal: fix actionable CI failures and high/medium review feedback. Stop and report human approval, draft-readiness, and merge-readiness gates.
Requires:
  • authenticated 
    gh
  • uv
  • target repository root as cwd
  • skill-root-relative script paths, for example 
    scripts/fetch_pr_checks.py
目标：修复可执行的CI失败问题，处理高/中优先级的评审反馈。遇到人工批准、草稿就绪和合并就绪闸门时，需停止并上报。
前置要求：
  • 已认证的
    gh
  • uv
  • 当前工作目录为目标仓库的根目录
  • 脚本路径相对于技能根目录，例如
    scripts/fetch_pr_checks.py

Bundled Scripts

内置脚本

ScriptRunOutput
scripts/fetch_pr_checks.py
uv run scripts/fetch_pr_checks.py [--pr NUMBER]
JSON: 
pr
, 
summary
, 
checks
, failure snippets
scripts/fetch_pr_feedback.py
uv run scripts/fetch_pr_feedback.py [--pr NUMBER]
JSON buckets: 
high
, 
medium
, 
low
, 
bot
, 
resolved
scripts/monitor_pr_checks.py
uv run scripts/monitor_pr_checks.py [--pr NUMBER]
terminal marker plus tab-separated checks
scripts/reply_to_thread.py
uv run scripts/reply_to_thread.py THREAD_ID BODY [...]
JSON reply results
Check summary fields include 
failed
, 
pending
, 
actionable_pending
, and 
human_gate_pending
.
Monitor markers:
  • ALL_CHECKS_PASSED
  • CHECKS_DONE_WITH_FAILURES
  • NO_CHECKS_REGISTERED
  • DRAFT_PR_WITH_NO_CHECKS
  • CHECKS_BLOCKED_BY_REVIEW_GATE
脚本运行命令输出
scripts/fetch_pr_checks.py
uv run scripts/fetch_pr_checks.py [--pr NUMBER]
JSON格式数据：包含
pr
、
summary
、
checks
以及失败代码片段
scripts/fetch_pr_feedback.py
uv run scripts/fetch_pr_feedback.py [--pr NUMBER]
JSON分类数据：
high
、
medium
、
low
、
bot
、
resolved
scripts/monitor_pr_checks.py
uv run scripts/monitor_pr_checks.py [--pr NUMBER]
终端标记符加制表符分隔的检查任务信息
scripts/reply_to_thread.py
uv run scripts/reply_to_thread.py THREAD_ID BODY [...]
JSON格式的回复结果
检查摘要字段包含
failed
、
pending
、
actionable_pending
和
human_gate_pending
。
监控标记符：
  • ALL_CHECKS_PASSED
  • CHECKS_DONE_WITH_FAILURES
  • NO_CHECKS_REGISTERED
  • DRAFT_PR_WITH_NO_CHECKS
  • CHECKS_BLOCKED_BY_REVIEW_GATE

Workflow

工作流程

1. Identify PR

1. 确定目标PR

Run:
bash
gh pr view --json number,url,headRefName,isDraft,reviewDecision
Stop when:
  • no PR exists
  • draft PR has no checks after monitor grace period: report 
    DRAFT_PR_WITH_NO_CHECKS
Draft rule: inspect existing checks/feedback only. Do not mark ready for review unless asked.
运行命令：
bash
gh pr view --json number,url,headRefName,isDraft,reviewDecision
在以下情况时停止：
  • 不存在对应PR
  • 草稿PR在监控宽限期后仍无检查任务：上报
    DRAFT_PR_WITH_NO_CHECKS
草稿规则：仅检查现有任务/反馈。除非被要求，否则不要标记为可评审状态。

2. Handle Feedback

2. 处理评审反馈

Run 
uv run scripts/fetch_pr_feedback.py [--pr NUMBER]
.
BucketAction
high
fix
medium
fix
low
ask user which to address
bot
skip informational comments
resolved
skip
Feedback fix checklist:
  • verify root cause
  • search related code
  • fix all instances
  • for 
    review_bot: true
    : fix real issues, explain false positives
Low-priority prompt format:
text
Found 3 low-priority suggestions:
1. [l] "Consider renaming this variable" - @reviewer in api.py:42
2. [nit] "Could use a list comprehension" - @reviewer in utils.py:18
3. [style] "Add a docstring" - @reviewer in models.py:55

Which should I address? ("1,3", "all", or "none")
运行
uv run scripts/fetch_pr_feedback.py [--pr NUMBER]
。
分类操作
high
修复
medium
修复
low
询问用户需要处理哪些
bot
跳过信息性评论
resolved
跳过
反馈修复检查清单：
  • 验证根本原因
  • 搜索相关代码
  • 修复所有相关实例
  • 若为
    review_bot: true
    ：修复真实问题，解释误报情况
低优先级建议提示格式：
text
发现3条低优先级建议：
1. [l] "考虑重命名此变量" - @reviewer 在 api.py:42
2. [nit] "可使用列表推导式" - @reviewer 在 utils.py:18
3. [style] "添加文档字符串" - @reviewer 在 models.py:55

需要处理哪些？（输入"1,3"、"all"或"none"）

3. Check CI Status

3. 检查CI状态

Run 
uv run scripts/fetch_pr_checks.py [--pr NUMBER]
.
StateAction
failed > 0
and 
actionable_pending == 0
fix failures
actionable_pending > 0
wait; poll feedback while waiting
pending > 0
and 
actionable_pending == 0
report 
CHECKS_BLOCKED_BY_REVIEW_GATE
no checks after grace periodreport 
NO_CHECKS_REGISTERED
or 
DRAFT_PR_WITH_NO_CHECKS
all actionable checks passedrun post-CI feedback check
Wait for actionable review bots: sentry, warden, cursor, bugbot, seer, codeql. Do not wait for approval, 
isDraft
, 
REVIEW_REQUIRED
, Codecov, or informational bots.
运行
uv run scripts/fetch_pr_checks.py [--pr NUMBER]
。
状态操作
failed > 0
且 
actionable_pending == 0
修复失败问题
actionable_pending > 0
等待；等待期间轮询反馈
pending > 0
且 
actionable_pending == 0
上报
CHECKS_BLOCKED_BY_REVIEW_GATE
宽限期后仍无检查任务上报
NO_CHECKS_REGISTERED
或
DRAFT_PR_WITH_NO_CHECKS
所有可执行检查通过执行CI后反馈检查
等待可自动处理的评审机器人：sentry、warden、cursor、bugbot、seer、codeql。 无需等待人工批准、
isDraft
状态、
REVIEW_REQUIRED
、Codecov或信息类机器人。

4. Fix CI Failures

4. 修复CI失败问题

For each failure:
  1. read full log: 
    gh run view <run-id> --log-failed
  2. trace from assertion/exception/lint rule to source
  3. state the cause before editing: "fails because X, affected by Y"
  4. search related call sites/patterns
  5. fix root cause, not symptom
  6. add focused test coverage when needed
针对每个失败问题：
  1. 查看完整日志：
    gh run view <run-id> --log-failed
  2. 从断言/异常/lint规则追踪到源代码
  3. 在编辑前说明原因："失败原因是X，受Y影响"
  4. 搜索相关调用位置/模式
  5. 修复根本原因，而非表面症状
  6. 必要时添加针对性测试覆盖

5. Verify Locally, Then Commit and Push

5. 本地验证后提交并推送

Before commit:
  • test fix: rerun specific test
  • lint/type fix: rerun affected checker
  • code fix: rerun covering tests
  • local failure: fix before pushing
bash
git add <files>
git commit -m "fix: <descriptive message>"
git push
提交前：
  • 测试修复：重新运行特定测试
  • 代码规范/类型修复：重新运行相关检查工具
  • 代码修复：重新运行覆盖性测试
  • 本地失败：推送前修复
bash
git add <files>
git commit -m "fix: <描述性信息>"
git push

6. Monitor CI and Address Feedback

6. 监控CI并处理新反馈

Loop:
  1. run 
    uv run scripts/fetch_pr_checks.py
  2. handle table in step 3
  3. while 
    actionable_pending > 0
    , run 
    uv run scripts/fetch_pr_feedback.py
  4. fix new high/medium feedback immediately
  5. if changed, verify, commit, push, restart loop
  6. otherwise sleep 30 seconds and repeat
  7. after checks pass, wait 10 seconds, fetch feedback once more
  8. if new high/medium feedback exists, return to step 4
Claude Code optional: run 
uv run scripts/monitor_pr_checks.py
through 
MonitorTool
with 
persistent: false
; set timeout to normal repo CI duration. Restart the monitor after every push.
循环执行：
  1. 运行
    uv run scripts/fetch_pr_checks.py
  2. 按照步骤3的表格处理状态
  3. 当
    actionable_pending > 0
    时，运行
    uv run scripts/fetch_pr_feedback.py
  4. 立即处理新的高/中优先级反馈
  5. 若有修改，验证后提交、推送，重启循环
  6. 否则等待30秒后重复执行
  7. 检查通过后，等待10秒，再次获取反馈
  8. 若存在新的高/中优先级反馈，返回步骤4
可选使用Claude Code：通过
MonitorTool
运行
uv run scripts/monitor_pr_checks.py
，设置
persistent: false
；超时时间设为仓库常规CI时长。每次推送后重启监控。

Exit Conditions

退出条件

ExitConditions
Successactionable CI passed; post-CI feedback clean; low-priority choice handled
Ask usersame failure after 2 attempts; feedback unclear; infrastructure issue
Stopno PR; branch needs rebase; no checks; draft no-checks; only human gates remain
退出状态条件
成功可执行的CI检查通过；CI后反馈无问题；低优先级选项已处理
询问用户同一失败问题尝试2次后仍未解决；反馈不明确；基础设施问题
停止无PR；分支需要变基；无检查任务；草稿PR无检查任务；仅剩余人工闸门

Fallback

备选方案

If scripts fail, use 
gh
CLI directly:
  • gh pr view --json number,url,headRefName,isDraft,reviewDecision
  • gh pr checks --json name,state,bucket,description,link
  • gh run view <run-id> --log-failed
  • gh api repos/{owner}/{repo}/pulls/{number}/comments
如果脚本执行失败，直接使用
gh
CLI：
  • gh pr view --json number,url,headRefName,isDraft,reviewDecision
  • gh pr checks --json name,state,bucket,description,link
  • gh run view <run-id> --log-failed
  • gh api repos/{owner}/{repo}/pulls/{number}/comments