PR-maintenance Claude code SKILL.md

PR-maintenance Claude code SKILL.md

name	pr-maintenance
description	Performs comprehensive PR maintenance — rebases onto main, scans GitHub Actions failures, surfaces unaddressed review comments, auto-applies thumbs-up-reacted suggestions, and does an independent code review. Use when the user wants to catch up on a PR, fix CI, address review comments, or do general PR hygiene. Accepts a GitHub URL, PR number, or auto-detects from the current branch.
argument-hint	[pr-url|pr-number] [--codebase path]

PR Maintenance

Description

Performs end-to-end pull request maintenance: rebases onto main, identifies GitHub Actions failures, surfaces and triages review comments (new, reacted, pending reply), performs an independent code review, and commits approved changes. Each change requires explicit user confirmation before being applied. No specialists are dispatched — the supervisor handles this directly.

Usage

/pr-maintenance                                        # auto-detect PR from current branch
/pr-maintenance 1234                                   # PR number in current repo
/pr-maintenance https://github.com/org/repo/pull/1234  # full GitHub URL
/pr-maintenance 1234 --codebase /path/to/repo          # explicit repo path

Options:

• First positional argument: PR number or full GitHub PR URL (optional — auto-detects from current branch if omitted)
• --codebase: Path to repository (defaults to current working directory)

Instructions

You are the Supervisor for PR maintenance. This is a direct-execution skill — no specialists are dispatched.

Step 1: Resolve PR

Announce: [pr-maintenance][Step 1] - Resolve PR

Extract flags:

• codebase: Working directory (defaults to current directory)
• pr_input: First positional argument (PR number, GitHub URL, or empty)

Resolve the PR reference:

1. GitHub URL provided: Extract owner, repo, and PR number from URL pattern https://github.com/{owner}/{repo}/pull/{number}.

2. PR number provided: Use the number directly. Determine owner/repo from the codebase:

   cd [codebase] && git remote get-url origin

   Parse the owner and repo from the remote URL.

3. Nothing provided: Detect from current branch:

   cd [codebase] && git branch --show-current

   Then find the PR for this branch using mcp__github__list_pull_requests with head filter set to {owner}:{branch}. If no PR is found, report and stop:

   No open PR found for branch '$CURRENT_BRANCH'.
   Provide a PR number or URL: /pr-maintenance <number|url>
   

Track: PR_NUMBER, OWNER, REPO, CODEBASE.

Verify the PR exists and is open using mcp__github__pull_request_read with method get:

• Extract: state, headRefName, baseRefName, title, url, author

If state is not open, report and stop.

Track: PR_BRANCH, BASE_BRANCH, PR_TITLE, PR_URL, PR_AUTHOR.

Checkout the PR branch locally:

cd [codebase]
git fetch origin
git checkout $PR_BRANCH
git pull origin $PR_BRANCH

Step 2: Fetch PR Details & Comments

Announce: [pr-maintenance][Step 2] - Fetch PR Details & Comments

Fetch all review data using MCP tools:

1. Review comments (inline code comments): Use mcp__github__pull_request_read with method get_review_comments to get all review threads. Paginate if needed.

2. Conversation comments (issue-level): Use mcp__github__pull_request_read with method get_comments to get conversation-tab comments.

3. Reviews (approve/request changes): Use mcp__github__pull_request_read with method get_reviews.

For each review comment thread, note:

• id, body, path, line, diff_hunk
• created_at, user.login
• Whether the thread isResolved
• Reply chain (comments within the thread)

To check reactions on comments, use:

gh api repos/{owner}/{repo}/pulls/comments/{comment_id}/reactions

Determine the last commit push time:

git log -1 --format='%aI' origin/$PR_BRANCH

Classify each top-level review comment into buckets:

• thumbs_up: Has a +1 reaction from PR_AUTHOR — these are accepted suggestions
• replied: Has a reply from PR_AUTHOR in the thread OR the thread isResolved
• new: No reply from PR_AUTHOR, no +1 reaction, comment created after last commit push
• pending_reply: No reply from PR_AUTHOR, no +1 reaction, comment created before last commit push

Store: COMMENTS_THUMBS_UP, COMMENTS_NEW, COMMENTS_PENDING_REPLY, COMMENTS_REPLIED.

Step 3: Rebase onto Main

Announce: [pr-maintenance][Step 3] - Rebase onto Main

Check if the branch is behind base:

cd [codebase]
git fetch origin $BASE_BRANCH
BEHIND=$(git rev-list --count HEAD..origin/$BASE_BRANCH)

If $BEHIND is 0, announce the branch is up to date and skip to Step 4.

If behind, announce:

Branch '$PR_BRANCH' is $BEHIND commit(s) behind '$BASE_BRANCH'.
Rebasing onto origin/$BASE_BRANCH...

Perform the rebase:

cd [codebase]
git rebase origin/$BASE_BRANCH

If rebase conflicts occur:

1. List conflicting files: git diff --name-only --diff-filter=U
2. Show the conflict markers for each file
3. Ask the user how to resolve each conflict using AskUserQuestion
4. After resolution: git add [resolved-files] && git rebase --continue
5. If the user wants to abort: git rebase --abort and stop the skill

Track: REBASED = true | false (needed for force-push decision in Step 10).

Step 4: Scan GitHub Actions

Announce: [pr-maintenance][Step 4] - Scan GitHub Actions

Fetch check runs for the PR head commit using mcp__github__pull_request_read with method get_check_runs.

If all checks pass or are pending: Announce CI status and proceed to Step 5.

If there are failures:

For each failed check run, get detailed logs. Use mcp__github__get_job_logs with the failed job ID and return_content: true.

Analyze the failure and categorize:

• Test failure: A test assertion failed — read the failing test file and the related source code
• Lint failure: A linter rule was violated
• Build failure: Compilation or build error
• Flaky/infra: Timeout, network issue, runner problem (not actionable)

For each actionable failure, present to the user:

### CI Failure: [check name]

**Type**: [test|lint|build]
**Log excerpt**:
> [relevant log lines]

**Root cause**: [analysis]
**Proposed fix**: [description]

**Files to modify**:
- [file:line] — [change description]

Ask the user with AskUserQuestion:

• "Apply this fix?" (options: Yes / Skip / Let me handle it)

If approved, read the relevant files, apply the fix using Edit. Track all applied fixes as CI_FIXES_APPLIED.

Step 5: Triage Review Comments

Announce: [pr-maintenance][Step 5] - Triage Review Comments

Present a summary of comment classification from Step 2:

### PR Comment Triage

| Category | Count | Action |
|----------|-------|--------|
| Accepted (thumbs-up) | [n] | Will apply (Step 6) |
| New (unaddressed) | [n] | Will review (Step 7) |
| Pending reply | [n] | Will surface (Step 8) |
| Already replied/resolved | [n] | No action needed |

Total comments: [n]

Proceed through Steps 6, 7, 8 in order.

Step 6: Apply Thumbs-Up Comments

Announce: [pr-maintenance][Step 6] - Apply Thumbs-Up Comments

If COMMENTS_THUMBS_UP is empty, announce "No accepted suggestions to apply" and skip to Step 7.

For each thumbs-up comment:

1. Read the comment body — look for GitHub suggestion blocks (```suggestion) or plain-text change descriptions
2. Read the target file at the referenced path and line
3. Determine the code change needed

Present each change:

### Accepted Suggestion [n/total]

**From**: @[reviewer] on [file]:[line]
**Comment**: [body]

**Proposed change**:
[show diff: old lines -> new lines]

Ask with AskUserQuestion:

• "Apply this accepted suggestion?" (options: Apply / Skip)

Apply approved changes using Edit. Track as SUGGESTIONS_APPLIED.

Step 7: Surface New Comments

Announce: [pr-maintenance][Step 7] - Surface New Comments

If COMMENTS_NEW is empty, announce "No new comments to address" and skip to Step 8.

For each new (unaddressed) comment:

1. Read the comment body and diff hunk
2. Read the referenced file and surrounding lines for context
3. Determine if the comment requests a code change or is a question/discussion

Present each:

### New Comment [n/total]

**From**: @[reviewer] on [file]:[line]
**Comment**: [body]
**Type**: [Code change request | Question | Discussion]

**Current code**:
[relevant code lines from the file]

If it's a code change request, also show:

**Proposed change**:
[show diff: old lines -> new lines]

Ask with AskUserQuestion:

• For code changes: "How to handle this comment?" (options: Apply proposed fix / Skip / Let me handle it)
• For questions: "This comment needs a reply. Would you like to reply now?" (options: Reply / Skip)

If the user chooses "Reply", ask them for the reply text, then post it using mcp__github__add_reply_to_pull_request_comment with the comment ID and the user's reply body.

Apply approved code changes using Edit. Track as NEW_COMMENTS_APPLIED.

Step 8: Surface Pending Reply Comments

Announce: [pr-maintenance][Step 8] - Surface Pending Reply Comments

If COMMENTS_PENDING_REPLY is empty, announce "No comments awaiting reply" and skip to Step 9.

Present all pending-reply comments together:

### Comments Awaiting Your Reply

These comments were left before your last push and haven't been addressed:

---
**[n]. @[reviewer]** on `[file]:[line]` ([date])
> [comment body]

---

Ask with AskUserQuestion:

• "Would you like to address any of these comments?" (options: Address them one by one / Skip all / Let me handle them later)

If addressing one by one, for each comment:

• If it requests a code change, show the proposed change and ask for approval (apply with Edit)
• If it's a question, ask the user for reply text and post it using mcp__github__add_reply_to_pull_request_comment
• If it can be resolved by code already changed, suggest replying with the resolution

Step 9: Independent Code Review

Announce: [pr-maintenance][Step 9] - Independent Code Review

Perform a fresh code review of the entire PR diff. Get the diff using mcp__github__pull_request_read with method get_diff.

Also get the PR description using mcp__github__pull_request_read with method get and read the body field.

Review the diff for:

1. Bugs: Logic errors, off-by-one, null/nil handling, race conditions
2. Security: Injection vulnerabilities, auth issues, secrets exposure
3. Performance: N+1 queries, unbounded loops, missing indexes
4. Style: Inconsistency with surrounding code patterns
5. Missing tests: New logic paths without test coverage
6. Missing edge cases: Error handling, boundary conditions
7. Dead code: Unused variables, unreachable branches

Skip anything already raised by existing review comments — this review should surface new findings only.

If no issues found:

### Code Review: Clean

No additional issues found in the PR diff.

If issues are found:

### Code Review Findings

Found [n] issue(s):

---
**[severity: Critical|Warning|Suggestion] [n/total]**: [title]
**File**: [file]:[line]
**Current code**:
[relevant lines]

**Issue**: [description]
**Proposed fix**:
[show diff]

---

Ask with AskUserQuestion:

• For each finding: "Apply this fix?" (options: Apply / Skip / Let me handle it)

Apply approved fixes using Edit. Track as REVIEW_FIXES_APPLIED.

Step 10: Commit & Push

Announce: [pr-maintenance][Step 10] - Commit & Push

Check if any changes were made:

cd [codebase]
git status --porcelain

If no file changes were made:

• If REBASED is true, force-push the rebase:

  git push --force-with-lease origin $PR_BRANCH

• If REBASED is false, announce "No changes to push" and skip to Step 11.

If there are file changes:

Stage and commit all changes:

cd [codebase]
git add -A
git commit -m "$(cat <<'EOF'
Address PR review feedback

Applied changes:
- [list each CI fix applied]
- [list each suggestion applied]
- [list each new comment fix applied]
- [list each review fix applied]

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Ask the user with AskUserQuestion before pushing:

• If rebased: "Ready to force-push? (rebase + changes)" (options: Push / Review changes first / Abort)
• If not rebased: "Ready to push?" (options: Push / Review changes first / Abort)

If "Review changes first", show git diff HEAD~1 and ask again.

Push:

cd [codebase]
if [ "$REBASED" = "true" ]; then
  git push --force-with-lease origin $PR_BRANCH
else
  git push origin $PR_BRANCH
fi

Step 11: Complete

Announce: [pr-maintenance][Step 11] - Complete

## PR Maintenance Complete

**PR**: [PR_URL] — [PR_TITLE]
**Branch**: [PR_BRANCH] -> [BASE_BRANCH]

### Actions Taken

| Action | Status |
|--------|--------|
| Rebase onto $BASE_BRANCH | [Done (n commits) / Already up to date / Skipped] |
| CI Failures | [n fixed / All green / n skipped] |
| Accepted suggestions applied | [n applied / None] |
| New comments addressed | [n applied, n replied, n skipped] |
| Pending reply comments | [n addressed, n surfaced] |
| Code review findings | [n fixed / Clean / n skipped] |
| Push | [Pushed / Force-pushed / No changes] |

### Changes Made
- [file:line] [description]

### Remaining Items
- [Any skipped comments or fixes that need manual attention]
- [Any comments that still need replies]

Stop here. PR maintenance is complete.

---

Important Rules

• Rebase first: Always rebase before applying any code changes to avoid conflicts on stale code
• User confirmation for every change: Never apply a code change without explicit user approval via AskUserQuestion
• Force-push only after rebase: Use --force-with-lease (never --force) and only when the branch was rebased
• Preserve comment context: When showing comments, always include the surrounding code context and diff hunk
• One commit for all changes: Batch all approved changes into a single commit (not one commit per change)
• Classify comments accurately: Use reactions and reply chains to determine comment status — do not guess
• Independent review is independent: The code review in Step 9 should find only issues not already raised in comments
• No auto-merge: Never merge the PR — merging is a human decision
• No scope creep: Only fix what is identified in CI failures, review comments, or the code review — do not refactor surrounding code
• Respect skips: If the user skips a suggestion or fix, do not re-raise it or include it in the commit
• Use MCP for GitHub reads: Use mcp__github__pull_request_read for PR data, mcp__github__get_job_logs for CI logs, mcp__github__add_reply_to_pull_request_comment for posting replies
• Use Edit for code changes: Apply all code modifications through the Edit tool, not bash commands
• No specialists: This is a direct-execution skill — the supervisor handles everything