---
name: maintain-pr
description: >
  Maintain and follow up on a single Docker documentation pull request that
  you own or are responsible for updating. Check CI and review feedback, fix
  actionable failures, push changes, reply to comments, and report status.
  Use for requests such as "babysit this PR", "check the status of my PR",
  "fix CI on my PR", or "address review comments on #500". Do not use for
  maintainer review of an incoming contribution; use review-pr for that.
---

# Maintain PR

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

```bash
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:

1. Format and validate the changed files.
2. Commit and push the focused change.
3. Reply to every addressed thread with what changed or why no change was
   made.
4. End replies with an accurate agent-disclosure footer, such as
   `Generated by Codex`.
5. Resolve threads only after replying.
6. Re-request review when appropriate.

Use the inline comment endpoint to reply:

```bash
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

```markdown
## 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>
```