pr-maintainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Maintainer

PR 维护技能

Follow the repository's PR maintenance policy/ADR, if one exists, when maintaining a PR created by Codex or Claude Code.

维护由Codex或Claude Code创建的PR时，若仓库存在PR维护政策/ADR，请遵循该政策。

When to Use

适用场景

Use this skill after an agent creates a PR, including a draft PR, or when asked to continue an agent-created PR through CI, review comments, repair commits, and merge.

Also use this skill immediately after an agent-created draft PR becomes ready for review, even when the ready-for-review transition was performed manually by the user outside the agent session. Treat that transition as the start signal for CI and review-state monitoring.

If the PR was opened as draft only because repository workflow says to create draft PRs, and the implementation has already passed the repository's agreed local validation (see the project's testing rules for the exact CI-equivalent filter), mark it ready for review in the same session and immediately enter the polling workflow. Do not leave a reviewable draft PR idle just because it was created with

--draft

This skill is shared by Codex and Claude Code. GitHub I/O goes through

gh

; the agent-specific part is only the code-editing session that applies fixes in the existing worktree.

在Agent创建PR（包括草稿PR）后，或被要求跟进Agent创建的PR的CI、评审评论、修复提交及合并流程时，使用本技能。

在Agent创建的草稿PR转为就绪待评审状态后，也应立即使用本技能——即使用户在Agent会话外手动执行了该转就绪操作。应将该状态转换视为CI和评审状态监控的启动信号。

如果PR仅因仓库工作流要求创建草稿PR而以草稿形式提交，且实现已通过仓库约定的本地验证（确切的CI等效筛选规则请参见项目的测试规则），请在同一会话中将其标记为就绪待评审，并立即进入轮询工作流。不要仅因为PR是通过

--draft

创建的，就让可评审的草稿PR处于闲置状态。

本技能由Codex和Claude Code共用。GitHub交互通过

gh

完成；仅有的Agent专属部分是在现有worktree中应用修复的代码编辑会话。

Core Policy

核心策略

Continue in the same agent session and same dedicated worktree used to create the PR.
Create agent PRs ready for review by default. Do not pass
```
--draft
```
to
```
gh pr create
```
unless the user explicitly asked for draft-only publication or the implementation is not reviewable yet.

Immediately after creating a PR, enforce the no-draft postcondition before polling CI or setting up auto-merge:

bash

IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
if [ "$IS_DRAFT" = "true" ]; then
  gh pr ready "$PR"
fi

IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
if [ "$IS_DRAFT" = "true" ]; then
  echo "PR is still draft; aborting auto-merge setup."
  exit 1
fi

Do not stop at the draft PR URL when the PR is reviewable. First mark it ready for review, then immediately enter the polling workflow.
Leave a PR in draft only when the user explicitly asked for draft-only publication, local validation is incomplete or failing, the scope is intentionally not ready for review, or a blocker must be reported.
If the user says they manually changed a draft PR to ready, immediately enter the polling workflow.
Do not use
```
@codex fix
```
or GitHub comment-driven repair commands.
Poll for at most 20 minutes, every 3 minutes.
Use
```
gh
```
/
```
gh api
```
for PR state, checks, failed logs, comments, issue creation, labels, replies, and merge.
Repair CI failures and review findings in the same worktree, then run the repo's normal pre-push validation.
Reply to every review comment in Japanese.
Do not auto-resolve review threads.
Allow up to 4 repair loops.
If repair loops continue after the 4th attempt, or review fixes create more design-level review findings, stop and escalate to design discussion.
Merge without human intervention only when bot review has completed cleanly and required checks are clean.
Treat an empty review/comment set as "review not completed yet", not as clean.
Use squash merge.
After a PR is merged, immediately clean up the merged worktree under the project's worktree directory (see the repository's git-workflow rules) so its
```
.venv
```
and other build artifacts do not linger.

在创建PR时使用的同一Agent会话和同一专用worktree中继续操作。
Agent创建的PR默认设为就绪待评审状态。除非用户明确要求仅以草稿形式发布，或实现尚不具备评审条件，否则不要向
```
gh pr create
```
传递
```
--draft
```
参数。

创建PR后，在轮询CI或设置auto-merge之前，立即强制执行非草稿后置条件：

bash

IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
if [ "$IS_DRAFT" = "true" ]; then
  gh pr ready "$PR"
fi

IS_DRAFT="$(gh pr view "$PR" --json isDraft -q .isDraft)"
if [ "$IS_DRAFT" = "true" ]; then
  echo "PR is still draft; aborting auto-merge setup."
  exit 1
fi

当PR具备评审条件时，不要停留在草稿PR的URL页面。先将其标记为就绪待评审，然后立即进入轮询工作流。
仅当用户明确要求仅以草稿形式发布、本地验证未完成或失败、范围有意暂不准备评审，或必须报告阻塞问题时，才将PR保留为草稿状态。
如果用户表示已手动将草稿PR转为就绪状态，立即进入轮询工作流。
不要使用
```
@codex fix
```
或GitHub评论驱动的修复命令。
最多轮询20分钟，每3分钟轮询一次。
使用
```
gh
```
/
```
gh api
```
获取PR状态、检查结果、失败日志、评论，以及创建issue、管理标签、回复和合并操作。
在同一worktree中修复CI故障和评审发现的问题，然后运行仓库常规的推送前验证。
用日语回复每一条评审评论。
不要自动解决评审线程。
最多允许4次修复循环。
如果第4次尝试后仍需继续修复循环，或评审修复产生了更多设计层面的评审问题，停止操作并升级至设计讨论。
仅当机器人评审顺利完成且所有必需检查均通过时，才可在无人工干预的情况下合并。
评审/评论集为空时，视为「评审尚未完成」，而非评审通过。
使用squash merge方式合并。
PR合并后，立即清理项目worktree目录下已合并的worktree（参见仓库的git-workflow规则），避免其
```
.venv
```
和其他构建产物残留。

Polling Workflow

轮询工作流

After opening the PR, record the PR number and current head SHA in session memory. If

isDraft

is true, decide whether the PR is reviewable:

If reviewable, run
```
gh pr ready "$PR"
```
before polling.
If not reviewable, comment or report why maintenance cannot continue yet, and stop without merging.

Then loop until success, repair-needed, escalation, timeout, or merge.

Commands to gather state:

bash

gh pr view "$PR" --json \
  number,title,isDraft,headRefName,headRefOid,baseRefName,mergeStateStatus,reviewDecision,statusCheckRollup,labels

gh pr checks "$PR" --json name,state,bucket,link,startedAt,completedAt,workflow

Review completion gate:

Do not merge immediately after CI success.
Continue polling until the expected Codex/Bot review signal appears as a PR review, review comment, issue comment, issue reaction, or other repository-standard bot review artifact.
Codex review state is signaled by reactions from
```
chatgpt-codex-connector[bot]
```
on the PR issue:
- ```
eyes
```
  reaction: review is in progress - keep polling, do not merge yet.
- ```
+1
```
  reaction: clean review completed - treat as a completed clean bot review when there are no blocking review comments.
Codex findings are posted as inline pull request review comments, not issue-level comments.
```
gh pr view --comments
```
does not return inline review comments. Always fetch them separately using the pull request review comments endpoint. GitHub list endpoints are paginated; always pass
```
--paginate
```
and
```
per_page=100
```
so comments on later pages are not missed:
bash
```
gh api --paginate "repos/{OWNER}/{REPO}/pulls/$PR/comments?per_page=100" \
  --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {id, path, line, body: .body[:300]}]'
```
A Codex inline comment containing a P1 or P2 badge is a blocking finding. Treat any unresolved P1/P2 inline comment as "review has blocking findings" regardless of the
```
+1
```
reaction.
If CI is green but there are no reviews/comments/reactions yet, keep waiting until the 20 minute polling timeout.
Only treat review as clean after a bot review artifact exists and contains no blocking findings.
If no bot review artifact appears within 20 minutes, comment on the PR in Japanese that CI is green but review did not complete within the polling window, then stop without merging.

Commands to gather clean-reaction state:

bash

gh api --paginate "repos/{OWNER}/{REPO}/issues/$PR/reactions?per_page=100"

For any other

gh api

call against a GitHub list endpoint, use

--paginate

with

per_page=100

unless the endpoint is known to return a single resource. Do not infer "no review artifact" or "no blocking finding" from a first page only response.

For failed CI jobs, use

gh

to fetch failed logs:

bash

gh run view "$RUN_ID" --log-failed

Use

gh api

for review comments and review threads when

gh pr view

is insufficient. Keep GitHub API responses bounded and summarize large logs before reasoning over them.

创建PR后，将会话内存中记录PR编号和当前的head SHA。如果

isDraft

为true，判断PR是否具备评审条件：

若具备评审条件，在轮询前运行
```
gh pr ready "$PR"
```
。
若不具备评审条件，发表评论或报告无法继续维护的原因，然后停止操作，不执行合并。

然后进入循环，直到成功、需要修复、升级、超时或合并为止。

状态收集命令：

bash

gh pr view "$PR" --json \
  number,title,isDraft,headRefName,headRefOid,baseRefName,mergeStateStatus,reviewDecision,statusCheckRollup,labels

gh pr checks "$PR" --json name,state,bucket,link,startedAt,completedAt,workflow

评审完成门槛：

不要在CI成功后立即合并。
继续轮询，直到预期的Codex/机器人评审信号出现，形式包括PR评审、评审评论、issue评论、issue反应或其他仓库标准的机器人评审产物。
Codex评审状态通过
```
chatgpt-codex-connector[bot]
```
在PR对应的issue上的反应来标识：
- ```
eyes
```
  反应：评审进行中——继续轮询，暂不合并。
- ```
+1
```
  反应：评审顺利完成——当没有阻塞性评审评论时，视为机器人评审已完成且无问题。
Codex的发现会以Pull Request行内评审评论的形式发布，而非issue级评论。
```
gh pr view --comments
```
不会返回行内评审评论。始终通过Pull Request评审评论端点单独获取这些评论。GitHub的列表端点支持分页；请始终传递
```
--paginate
```
和
```
per_page=100
```
参数，避免遗漏后续页面的评论：
bash
```
gh api --paginate "repos/{OWNER}/{REPO}/pulls/$PR/comments?per_page=100" \
  --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {id, path, line, body: .body[:300]}]'
```
包含P1或P2标记的Codex行内评论属于阻塞性问题。无论是否有
```
+1
```
反应，任何未解决的P1/P2行内评论都应视为「评审存在阻塞性问题」。
如果CI通过但尚无评审/评论/反应，继续等待直到20分钟轮询超时。
仅当存在机器人评审产物且不包含阻塞性问题时，才视为评审通过。
如果20分钟内未出现机器人评审产物，用日语在PR下评论说明CI已通过但评审未在轮询窗口内完成，然后停止操作，不执行合并。

评审通过反应状态收集命令：

bash

gh api --paginate "repos/{OWNER}/{REPO}/issues/$PR/reactions?per_page=100"

对于其他任何针对GitHub列表端点的

gh api

调用，除非已知该端点返回单个资源，否则都应使用

--paginate

和

per_page=100

。不要仅根据第一页的响应就推断「无评审产物」或「无阻塞性问题」。

对于失败的CI任务，使用

gh

获取失败日志：

bash

gh run view "$RUN_ID" --log-failed

当

gh pr view

不足以获取评审评论和评审线程时，使用

gh api

。应对GitHub API响应做大小限制，在分析大日志前先进行摘要。

Repair Rules

修复规则

When CI fails or review comments require changes:

Read the failed logs and review comments.
Decide whether each finding is valid.
Apply the smallest coherent fix in the existing PR worktree.
Run the repository's normal validation before push, including tests, Ruff, and mypy as applicable.
Commit and push the repair.
Reply to every review comment in Japanese.

Reply format:

markdown

対応しました。

- 修正内容: ...
- 修正commit: ...
- 検証: `...` passed

If not changing code for a comment:

markdown

この指摘は対応不要と判断しました。

- 理由: ...
- 確認内容: ...

当CI失败或评审评论要求修改时：

阅读失败日志和评审评论。
判断每个问题是否有效。
在现有PR的worktree中应用最小且完整的修复。
推送前运行仓库常规验证，包括测试、Ruff和mypy（如适用）。
提交并推送修复内容。
用日语回复每一条评审评论。

回复格式：

markdown

対応しました。

- 修正内容: ...
- 修正commit: ...
- 検証: `...` passed

如果针对某条评论无需修改代码：

markdown

この指摘は対応不要と判断しました。

- 理由: ...
- 確認内容: ...

Escalation Rules

升级规则

Stop automatic repair and escalate when any of these occur:

The 4th repair attempt still does not clear CI or review findings.
Review comments recur in the same responsibility boundary after a repair.
The fix requires workflow/permission/secret changes.
The fix requires direct push to main/default branch or history rewriting.
The fix requires a large design change rather than local repair.

Allowed in automatic repair:

Application code changes
Tests
Docs
DB migrations
Dependency and lockfile updates

Not allowed in automatic repair:

```
.github/workflows/**
```
changes
GitHub Actions permission changes
Secret or environment configuration changes
Direct push to main/default branch
Git history rewriting
Large design rewrites

On escalation:

Add design/escalation labels to the PR when available.
Create a GitHub issue describing the design problem and options.
Comment on the PR in Japanese with the issue link, summary, options, and what user decision is needed.
Stop without merging.

发生以下任一情况时，停止自动修复并升级：

第4次修复尝试后仍未通过CI或解决评审问题。
修复后，同一职责范围内的评审评论再次出现。
修复需要修改工作流/权限/密钥。
修复需要直接推送到main/默认分支或改写历史记录。
修复需要进行大规模设计变更，而非局部修复。

自动修复允许的操作：

应用代码修改
测试
文档
数据库迁移
依赖和锁文件更新

自动修复不允许的操作：

```
.github/workflows/**
```
修改
GitHub Actions权限修改
密钥或环境配置修改
直接推送到main/默认分支
Git历史改写
大规模设计重写

升级时的操作：

如存在设计/升级标签，为PR添加这些标签。
创建GitHub issue，描述设计问题和可选方案。
用日语在PR下发表评论，附上issue链接、摘要、可选方案以及需要用户做出的决策。
停止操作，不执行合并。

Merge Rules

合并规则

Before merge, verify:

PR is not draft.
The PR creation postcondition confirmed
```
isDraft == false
```
; if the PR is still draft, do not run
```
gh pr merge --auto
```
.
Head SHA matches the last checked SHA.
Required checks are successful.
Bot review has completed and has no blocking findings.
PR reviews/comments or PR issue reactions contain an expected bot review artifact.
Repair loop count is below the escalation threshold.
The PR is not in escalation state.

Then run:

bash

gh pr merge "$PR" --squash --auto --delete-branch --match-head-commit "$HEAD_SHA"

After GitHub reports the PR as merged, switch to the shared checkout (project root) and remove the merged worktree. If the repository defines a cleanup automation target (for example

make worktree-cleanup-merged

), use it; otherwise remove the worktree directly:

bash

cd "$PROJECT_ROOT"
git worktree remove "$WORKTREE_PATH"

Do not leave the merged worktree or its

.venv

behind.

合并前，请验证：

PR不是草稿状态。
PR创建后置条件已确认
```
isDraft == false
```
；如果PR仍为草稿状态，不要运行
```
gh pr merge --auto
```
。
Head SHA与上次检查的SHA一致。
所有必需检查均已通过。
机器人评审已完成且无阻塞性问题。
PR评审/评论或PR对应的issue反应中包含预期的机器人评审产物。
修复循环次数低于升级阈值。
PR未处于升级状态。

然后运行：

bash

gh pr merge "$PR" --squash --auto --delete-branch --match-head-commit "$HEAD_SHA"

GitHub报告PR已合并后，切换到共享检出目录（项目根目录）并删除已合并的worktree。如果仓库定义了清理自动化目标（例如

make worktree-cleanup-merged

），则使用该目标；否则直接删除worktree：

bash

cd "$PROJECT_ROOT"
git worktree remove "$WORKTREE_PATH"

不要遗留已合并的worktree或其

.venv

目录。

State

状态管理

Keep loop count, latest checked head SHA, and review-generation observations in session memory. Do not add persistent state for now. If the session is lost, stop; the user will give a fresh instruction.

将循环次数、最新检查的head SHA以及评审生成观察结果保存在会话内存中。暂不添加持久化状态。如果会话丢失，停止操作；用户会给出新的指令。

References

参考资料

The repository's PR maintenance ADR/policy doc, if one exists (for example under
```
docs/decisions/
```
)
```
AGENTS.md
```
/
```
CLAUDE.md
```
, if present

仓库的PR维护ADR/政策文档（如存在，例如位于
```
docs/decisions/
```
目录下）
```
AGENTS.md
```
/
```
CLAUDE.md
```
（如存在）