pr-autoloop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Autoloop

PR自动循环

Automatically drive the agent PR maintenance loop to a terminal state after a PR is created, without a human restarting each poll. This skill is shared by Codex and Claude Code; only the non-blocking wait mechanism differs per agent and is absorbed by each agent guide (see "Per-Agent Wait Mechanism").

This is a bounded time-based loop with goal-based stop conditions. It polls an external system (GitHub PR state) on an interval, reacts to changed CI/review/mergeability state, and stops only on merge, escalation, or timeout. Do not use it as a generic autonomous coding loop; it exists for the well-defined PR maintenance workflow.

在PR创建后，自动驱动Agent PR维护循环进入终止状态，无需人工重启每次轮询。该技能由Codex和Claude Code共享；仅非阻塞等待机制因Agent而异，且由各Agent指南说明（见「各Agent等待机制」）。

这是一个有时间限制、基于目标停止条件的循环。它会定期轮询外部系统（GitHub PR状态），对CI/审核/可合并性状态的变化做出反应，仅在合并、上报或超时时停止。请勿将其用作通用的自主编码循环；它专为明确的PR维护工作流设计。

Relationship to pr-maintainer

与pr-maintainer的关系

This skill is the autonomous looping layer. It does not define policy.

All policy - draft gates, repair rules, repair-loop limit (4), Japanese review replies, design escalation, merge conditions, post-merge worktree cleanup - comes from the
```
pr-maintainer
```
skill and the repository's PR maintenance ADR/policy, if one exists.
This skill only specifies the contract for how to keep the loop running by itself until a terminal state.

If anything here appears to conflict with

pr-maintainer

pr-maintainer

wins on policy and this skill wins only on "do not stall waiting for a human between polls".

该技能是自主循环层，不定义策略。

所有策略——草稿准入条件、修复规则、修复循环上限（4次）、日语审核回复、设计上报、合并条件、合并后worktree清理——均来自
```
pr-maintainer
```
技能以及代码仓库的PR维护ADR/策略（若存在）。
本技能仅定义如何让循环自主运行直至终止状态的契约。

如果此处的任何内容与

pr-maintainer

冲突，策略方面以

pr-maintainer

为准，本技能仅在「轮询之间不得因等待人工而停滞」这一点上优先。

When to Use

何时使用

Use immediately when any of these is true:

This agent just created a PR (
```
gh pr create
```
), including a draft created only because workflow says so.
A draft agent PR transitioned to ready for review (including a manual transition by the user).
The user asks to continue/finish an agent-created PR through CI, review, repair, and merge.

First enforce the no-draft postcondition from

pr-maintainer

(ready the PR if it is reviewable), then enter the loop. Do not stop at the PR URL when the PR is reviewable.

满足以下任一条件时立即使用：

本Agent刚创建了一个PR（
```
gh pr create
```
），包括仅因工作流要求而创建的草稿PR。
一个Agent创建的草稿PR转为待审核状态（包括用户手动转换的情况）。
用户要求将Agent创建的PR走完CI、审核、修复和合并流程。

首先执行

pr-maintainer

中的「非草稿后置条件」（若PR可审核则将其转为就绪状态），然后进入循环。当PR可审核时，不要停留在PR URL页面就结束。

Autoloop Contract (agent-agnostic)

自动循环契约（与Agent无关）

Treat maintenance as a self-paced poll loop. One loop cycle:

Gather state with

gh

- all four checks are mandatory every cycle; never skip based on CI status:

bash

# (a) PR fields - isDraft, mergeStateStatus, reviewDecision, head SHA
gh pr view "$PR" --repo "$REPO" \
  --json number,isDraft,headRefOid,mergeStateStatus,reviewDecision,statusCheckRollup,labels

# (b) Check run statuses
gh pr checks "$PR" --repo "$REPO" \
  --json name,state,bucket,link,startedAt,completedAt,workflow

# (c) Bot reactions on the PR issue (Codex signals: +1=clean, eyes=in-progress)
gh api --paginate "repos/$REPO/issues/$PR_NUM/reactions?per_page=100"

# (d) Inline review comments - detect P1/P2 badge findings from Codex
gh api --paginate "repos/$REPO/pulls/$PR_NUM/comments?per_page=100"

$REPO

owner/repo

(e.g.

your-org/your-repo

mergeStateStatus=CLEAN

means GitHub merge preconditions pass; it does not mean bot review is complete.

Classify the cycle into exactly one outcome:
- continue - any of these: CI checks still running (step b has pending checks); no
```
chatgpt-codex-connector[bot]
```
  reaction yet on the PR issue (step c is empty or only
```
eyes
```
  ); CI is green but Codex review/reaction has not posted yet → schedule the next cycle.
- repair - any of these: CI checks failed (step b); Codex review state is
```
COMMENTED
```
  and step d contains P1/P2 badge findings → fix in the PR worktree, validate, push, reply in Japanese per
```
pr-maintainer
```
  , then continue (count the repair against the limit).
- escalate - repair limit reached, recurring findings in the same boundary, or a forbidden change is required → open the design issue, comment in Japanese, stop.
- merge - all of the following are true (verified from step 1 data above):
  1. CI: all required checks pass (step b - no failed or pending).
  2. Draft:
```
isDraft == false
```
    (step a).
  3. Codex reaction:
```
chatgpt-codex-connector[bot]
```
    has a
```
+1
```
    reaction on the PR issue (step c).
```
eyes
```
    alone → continue, not merge.
  4. No blocking findings: step d has no unaddressed P1/P2 Codex comments.
  ⚠️
```
mergeStateStatus=CLEAN
```
  with
```
reviewDecision=""
```
  alone does not satisfy this gate. → squash merge, clean up the worktree, stop.
- timeout - total elapsed reached the polling window with no terminal result → comment in Japanese that CI/review did not complete in the window, stop.
If the outcome is continue, wait the poll interval and start the next cycle automatically.

The stop condition is not a prose judgment such as "the PR looks good". It is the conjunction of observable predicates gathered through

gh

: CI is green, the PR is not draft, the expected bot review artifact exists, no blocking findings remain, merge preconditions are clean, and the checked head SHA is still current.

将维护视为一个自定节奏的轮询循环。一个循环周期包含以下步骤：

使用

gh

收集状态——每个周期都必须完成全部四项检查；绝不能因CI状态跳过任何一项：

bash

# (a) PR fields - isDraft, mergeStateStatus, reviewDecision, head SHA
gh pr view "$PR" --repo "$REPO" \
  --json number,isDraft,headRefOid,mergeStateStatus,reviewDecision,statusCheckRollup,labels

# (b) Check run statuses
gh pr checks "$PR" --repo "$REPO" \
  --json name,state,bucket,link,startedAt,completedAt,workflow

# (c) Bot reactions on the PR issue (Codex signals: +1=clean, eyes=in-progress)
gh api --paginate "repos/$REPO/issues/$PR_NUM/reactions?per_page=100"

# (d) Inline review comments - detect P1/P2 badge findings from Codex
gh api --paginate "repos/$REPO/pulls/$PR_NUM/comments?per_page=100"

$REPO

为

owner/repo

格式（例如

your-org/your-repo

）。

mergeStateStatus=CLEAN

表示GitHub合并前置条件通过；不代表机器人审核已完成。

将本次循环的结果精确归类为以下一种：
- continue——满足以下任一条件：CI检查仍在运行（步骤b有待处理的检查）；PR议题上尚无
```
chatgpt-codex-connector[bot]
```
  的反应（步骤c为空或仅有
```
eyes
```
  ）；CI已通过但Codex审核/反应尚未发布→安排下一个循环。
- repair——满足以下任一条件：CI检查失败（步骤b）；Codex审核状态为
```
COMMENTED
```
  且步骤d包含P1/P2标记的问题→在PR的worktree中修复、验证、推送，按照
```
pr-maintainer
```
  的要求用日语回复，然后继续循环（修复次数计入上限）。
- escalate——达到修复上限、同一范围内反复出现问题，或需要进行禁止的变更→创建设计议题，用日语评论，停止循环。
- merge——所有以下条件均满足（通过上述步骤1的数据验证）：
  1. CI：所有必需检查均通过（步骤b——无失败或待处理项）。
  2. 草稿状态：
```
isDraft == false
```
    （步骤a）。
  3. Codex反应：
```
chatgpt-codex-connector[bot]
```
    在PR议题上有
```
+1
```
    反应（步骤c）。仅有
```
eyes
```
    →continue，不合并。
  4. 无阻塞性问题：步骤d中没有未处理的P1/P2级Codex评论。
  ⚠️ 仅
```
mergeStateStatus=CLEAN
```
  且
```
reviewDecision=""
```
  不满足该准入条件。 →执行squash merge，清理worktree，停止循环。
- timeout——总耗时达到轮询窗口时长仍未得到终止结果→用日语评论说明CI/审核未在窗口内完成，停止循环。
如果结果为continue，等待轮询间隔后自动启动下一个周期。

停止条件不是「PR看起来不错」这类主观判断，而是通过

gh

收集到的可观测谓词的组合：CI通过、PR非草稿、预期的机器人审核产物存在、无遗留阻塞性问题、合并前置条件满足，且所检查的head SHA仍为最新版本。

Loop parameters

循环参数

Poll interval: about 3 minutes between cycles.
Polling window: at most 20 minutes total (about 6-7 cycles).
Keep loop count and the last checked head SHA in session memory; track repair count with a todo.
Never let the loop idle waiting for a human to manually re-trigger the next poll. The whole point of this skill is that "continue" reschedules itself.

轮询间隔：每个周期间隔约3分钟。
轮询窗口：总时长最多20分钟（约6-7个周期）。
在会话内存中保存循环次数和上次检查的head SHA；用待办事项跟踪修复次数。
绝不能让循环因等待人工手动触发下一次轮询而闲置。本技能的核心意义就在于「continue」状态会自动重新调度。

Per-Agent Wait Mechanism

各Agent等待机制

The only agent-specific part is how you wait the poll interval without blocking your runtime. Do not hardcode a single mechanism here; follow your agent guide:

Claude Code → ScheduleWakeup self-pacing; fallback bounded
```
bash until
```
loop; never
```
sleep && <next>
```
.
Codex → inline session polling (no ScheduleWakeup). Keep the loop inside the active session and report the terminal state instead of relying on a platform routine to wake the agent later.

導入先の

CLAUDE.md

AGENTS.md

に wait 機構のセクション (例: "pr-autoloop 実装") があればそれを優先する。無ければ上のデフォルトに従い、どの機構を使ったか報告する。

唯一与特定Agent相关的部分是如何在不阻塞运行时的前提下等待轮询间隔。不要在此处硬编码单一机制；请遵循你的Agent指南：

Claude Code → 使用ScheduleWakeup自定节奏；备用方案为有界
```
bash until
```
循环；禁止使用
```
sleep && <next>
```
的方式。
Codex → 内联会话轮询（无ScheduleWakeup）。将循环保留在活动会话内并报告终止状态，而不是依赖平台例程稍后唤醒Agent。

如果目标项目的

CLAUDE.md

AGENTS.md

中存在等待机制相关章节（例如「pr-autoloop 实现」），则优先遵循该章节。若无，则按照上述默认方式执行，并报告所使用的机制。

Stop Conditions

停止条件

Stop the loop (and report the final monitored state) on merge, escalate, or timeout. Do not merge on continue, and do not treat an empty review/comment set as a clean review (it means "review not completed yet" per

pr-maintainer

在merge、escalate或timeout状态下停止循环（并报告最终监控状态）。处于continue状态时不要合并，也不要将空的审核/评论集视为审核通过（根据

pr-maintainer

的定义，这意味着「审核尚未完成」）。

References

参考资料

```
pr-maintainer
```
skill - policy this skill executes.
The repository's PR maintenance ADR/policy doc, if one exists (for example under
```
docs/decisions/
```
).
導入先の
```
CLAUDE.md
```
/
```
AGENTS.md
```
- per-agent wait mechanism のプロジェクト上書き (任意)。

```
pr-maintainer
```
技能——本技能所执行的策略。
代码仓库的PR维护ADR/策略文档（若存在，例如在
```
docs/decisions/
```
目录下）。
目标项目的
```
CLAUDE.md
```
/
```
AGENTS.md
```
——各Agent等待机制的项目级覆盖配置（可选）。