Do one maintenance pass over the specified author-owned PR: inspect its state, fix actionable failures or feedback, reply to reviewers, and report the result. This workflow may modify the branch and GitHub because the user is asking to maintain the PR. Do not apply it to an incoming PR merely because the user asks to review or assess it.
1. Gather PR state
gh pr view <PR> --repo docker/docs --json state,title,url,headRefName,headRepositoryOwner,comments,reviews,reviewDecision
gh pr checks <PR> --repo docker/docs --json name,state,detailsUrl
gh api repos/docker/docs/pulls/<PR>/comments \
--jq '[.[] | {id, author: .user.login, body, path, line, in_reply_to_id}]'
Always check both top-level reviews and inline comments. A review with an
empty body may still contain line-level feedback. Confirm that the PR is one
the user owns or is authorized to update before checking out or pushing its
branch. If not, stop and use review-pr.
2. Handle terminal states
If merged, report the final state and identify unanswered review comments. Reply only when the user remains responsible for follow-up.
If closed without merge, read the closing context and report the reason. Common causes include maintainer rejection, supersession, or automation.
3. Diagnose CI failures
- Read the failure details.
- Determine whether the failure comes from the PR or predates it.
- Fix actionable failures in the PR's changed files.
- Report pre-existing or upstream failures without changing unrelated files.
Follow repository instructions for formatting, targeted linting, explicit staging, commits, and pushes. Preserve unrelated working-tree changes.
4. Address review feedback
Treat every review comment as a claim to verify. Implement it only when the evidence supports it; explain any evidence-based disagreement.
After each fix:
- Format and validate the changed files.
- Commit and push the focused change.
- Reply to every addressed thread with what changed or why no change was made.
- End replies with an accurate agent-disclosure footer, such as
Generated by Codex. - Resolve threads only after replying.
- Re-request review when appropriate.
Use the inline comment endpoint to reply:
gh api repos/docker/docs/pulls/<PR>/comments \
--method POST \
--field in_reply_to=<COMMENT_ID> \
--field body='<RESPONSE>'
Use GraphQL to retrieve unresolved review-thread IDs and resolve only the threads that were addressed. Do not silently fix feedback without replying.
5. Report
## PR #<number>: <title>
**State:** <open, merged, or closed>
**CI:** <passing, failing, or pending>
**Review:** <approved, changes requested, or pending>
**Action taken:** <changes, replies, and thread resolution, or none needed>