pr-autoloop

PR 自动循环

创建 PR 后，自动驱动 Agent PR 维护循环直至达到终止状态，无需人工重新启动每次轮询。Codex 和 Claude Code 共用此技能；不同 Agent 的非阻塞等待机制有所不同，相关差异由各 Agent 指南处理（参见“各 Agent 的等待机制”）。

这是一个有时限的循环，带有基于目标的停止条件。它按固定间隔轮询外部系统（GitHub PR 状态），对 CI、审核或可合并性状态的变化作出响应，并且只会在合并、升级处理或超时后停止。请勿将其用作通用自主编码循环；它仅适用于明确的 PR 维护工作流。

与 pr-maintainer 的关系

此技能负责自主循环层，不定义策略。

• 所有策略——草稿门槛、修复规则、修复循环上限（4）、日语审核回复、设计升级处理、合并条件、合并后工作树清理——均来自 pr-maintainer 技能，以及仓库的 PR 维护 ADR/策略（如有）。
• 此技能仅规定如何让循环自行持续运行，直至达到终止状态。

如果此处内容看似与 pr-maintainer 冲突，策略方面以 pr-maintainer 为准；此技能仅在“轮询之间不得停下来等待人工介入”这一点上优先。

何时使用

出现以下任一情况时，立即使用：

• 此 Agent 刚创建了 PR（gh pr create），包括仅因工作流要求而创建的草稿 PR。
• Agent 创建的草稿 PR 已转为准备审核状态（包括用户手动进行的转换）。
• 用户要求继续/完成 Agent 创建的 PR，直至通过 CI、审核、修复并合并。

首先执行 pr-maintainer 中禁止草稿 PR 的后置条件（如果 PR 已可审核，则将其设为准备审核状态），然后进入循环。若 PR 已可审核，不要只提供 PR URL 就停止。

Autoloop Contract（与 Agent 无关）

将维护视为按节奏轮询的循环。每个循环周期：

1. 使用 gh 收集状态——每个周期都必须执行以下四项检查；绝不能根据 CI 状态跳过：

   # (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 合并前置条件已满足；不表示机器人审查已完成。

2. 将本周期归类为以下一种结果：

   • continue - 符合以下任一情况：CI 检查仍在运行（步骤 b 中有待完成的检查）；PR 议题上尚无 chatgpt-codex-connector[bot] 的反应（步骤 c 为空或只有 eyes）；CI 已通过，但 Codex 尚未发布审查结果或反应 → 安排下一个周期。

   • repair - 符合以下任一情况：CI 检查失败（步骤 b）；Codex 审查状态为 COMMENTED，且步骤 d 中包含 P1/P2 徽标问题 → 在 PR 工作树中修复、验证、推送，按照 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 合并，清理工作树，然后停止。

   • timeout - 总用时已达到轮询时限，但仍无终止结果 → 用日语评论说明 CI/审查未能在时限内完成，然后停止。

3. 如果结果为 continue，等待轮询间隔后自动开始下一个周期。

停止条件不是“PR 看起来不错”之类的主观判断，而是通过 gh 收集到的可观测条件的组合：CI 已通过、PR 不是草稿、存在预期的机器人审查产物、没有遗留的阻塞问题、合并前置条件已满足，且已检查的 head SHA 仍为当前版本。

循环参数

• 轮询间隔：每个周期之间约 3 分钟。
• 轮询时限：总计最多 20 分钟（约 6-7 个周期）。
• 在会话记忆中保留循环次数和上次检查的 head SHA；使用 todo 跟踪修复次数。
• 绝不能让循环空等，指望人工重新触发下一次轮询。本技能的核心就是让“continue”自行安排下一次轮询。

各 Agent 的等待机制

唯一因 Agent 而异的部分是如何等待轮询间隔，同时不阻塞运行时。不要在此硬编码单一机制；请遵循你的 Agent 指南：

• Claude Code → 使用 ScheduleWakeup 自我调度；备用方案为有界 bash until 循环；绝不能使用 sleep && <next>。
• Codex → 在会话内轮询（不使用 ScheduleWakeup）。在活动会话中保持循环，并报告终止状态，不要依赖平台例程稍后唤醒 Agent。

如果目标项目的 CLAUDE.md / AGENTS.md 中有等待机制章节（例如“pr-autoloop 实现”），则优先遵循该章节。若没有，则遵循上述默认设置，并报告使用了哪种机制。

停止条件

当出现 merge、escalate 或 timeout 时，停止循环（并报告最终监控状态）。处于 continue 时不得合并；审查/评论集合为空也不能视为审查通过（根据 pr-maintainer，这表示“审查尚未完成”）。

参考资料

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