address-review

Prerequisites: Config loaded, PR number parsed.

Step 1A: Fetch PR Metadata

Extract owner/repo from git remote get-url origin (e.g. [email protected]:owner/repo.git → owner/repo), then run:

gh pr view <number> --repo <owner>/<repo> --json number,title,body,headRefName,state,reviewDecision,reviews,reviewRequests

Step 1B: Pre-flight Check

Verify the PR is open:

• If the PR is merged → warn: "This PR is already merged. Nothing to address." Stop.
• If the PR is closed → warn: "This PR is closed. Do you want to proceed anyway?" Use AskUserQuestion. If no → stop.

Step 1C: Fetch Review Comments

Run both in parallel:

gh api repos/<owner>/<repo>/pulls/<number>/reviews

gh api repos/<owner>/<repo>/pulls/<number>/comments

Step 1D: Filter to Actionable Comments

From the fetched comments, filter to actionable items:

Include:

• Unresolved comments/threads
• Comments requesting changes (not approvals or neutral comments with no actionable content)
• Inline code review comments with suggestions

Exclude:

• Bot-generated comments (author is a known bot: github-actions[bot], dependabot[bot], etc.)
• Already-resolved threads
• Comments that are purely informational with no action requested
• Outdated comments on code that no longer exists (GitHub outdated flag)

If no actionable comments remain after filtering → report "No actionable review comments found on this PR." and stop.

Prerequisites: PR metadata fetched, PR is open, actionable comments exist.

Step 2A: Locate Working Directory

Check if a worktree exists for this PR's branch:

git worktree list --porcelain

Scan the output for a worktree whose branch matches the PR's headRefName. Also check .worktrees/ directory.

Step 2B: Enter Working Directory

If worktree exists: Use it as the working directory for all subsequent phases.

If no worktree exists: Check out the PR branch:

gh pr checkout <number>

Step 2C: Ensure Branch is Up to Date

git pull --rebase origin <headRefName>

If the pull fails (e.g., conflicts), warn the user and ask how to proceed.

Prerequisites: Working in the PR branch, actionable comments filtered.

Step 3A: Group Comments

Group comments by reviewer and thread. For each thread, capture:

• Reviewer name
• File path and line range (if inline)
• Comment body
• Thread context (previous replies in the conversation)
• Comment ID (needed for replies in Phase 5)

Step 3B: Present Summary

Present a high-level summary to the user:

• Total actionable comments
• Count per reviewer
• Breakdown: how many are inline code comments vs. general PR comments

If user context was provided in $ARGUMENTS, mention it and explain how it steers your evaluation.

Step 3C: Evaluate Each Comment

For each comment/thread, evaluate using these principles:

1. Verify before implementing — check the reviewer's claim against the actual codebase. Is the issue real?
2. Technically sound? — does the suggestion make sense for this codebase's patterns and constraints?
3. YAGNI check — is the suggestion adding unnecessary complexity, over-engineering, or premature abstraction?
4. Conflict check — does it conflict with prior architectural decisions documented in CLAUDE.md or .claude/rules/?
5. Clarity check — is the feedback clear enough to implement, or is it ambiguous?

Step 3D: Recommend Actions

For each comment, recommend one of:

Step 3E: Implementation Order

Sort the "Fix" items by priority:

1. Blocking issues first — bugs, broken behavior, security concerns
2. Simple fixes second — naming, formatting, small logic changes
3. Complex fixes last — refactoring, architectural changes

Step 3F: User Approval

Present the full evaluation to the user: each comment with your recommended action and reasoning.

Use AskUserQuestion to confirm the plan. Options:

• Approve — proceed with the recommended actions
• Modify — user wants to change some actions

If "Modify": ask which comments to change and what action to take instead, then re-present.

Only proceed to Phase 4 after the user approves.

Prerequisites: User approved the action plan, working in the PR branch.

Process

For each comment marked Fix, in the priority order from Phase 3:

1. Read the relevant file(s) and understand the context around the comment
2. Make the code change
3. Run relevant tests (unit tests for the affected file/module)
4. If tests fail:
   • Analyze the failure
   • Fix the root cause
   • Re-run tests
   • If still failing after 3 attempts, stop and ask the user
5. Move to the next fix

After all individual fixes are applied, run the full build and test suite:

<build command from config or CLAUDE.md>
<test command from config or CLAUDE.md>

Error Recovery

If the full test suite fails after all fixes:

1. Identify which fix broke the tests
2. Attempt to fix the issue (up to 3 retries)
3. If still failing, report to the user with:
   • The exact error output
   • Which review comment's fix caused the failure
   • Your best hypothesis for the root cause

Prerequisites: All fixes implemented and tests passing (or user has approved proceeding despite failures).

Reply Templates

For each comment, post a reply based on the action taken:

Tone rules (from receiving-code-review principles):

• No performative gratitude — skip "Great point!", "Thanks for catching this!", etc.
• Technical acknowledgment only — state what was done or why not
• Be direct and concise

Posting Replies

For each inline review comment:

printf '%s' '<reply text>' > /tmp/claude/pr-reply-<comment-id>.md
REPLY=$(cat /tmp/claude/pr-reply-<comment-id>.md)
gh api repos/<owner>/<repo>/pulls/<number>/comments/<comment-id>/replies -f body="$REPLY"

For general PR review comments, post as a PR comment:

printf '%s' '<reply text>' > /tmp/claude/pr-comment.md
COMMENT=$(cat /tmp/claude/pr-comment.md)
gh pr comment <number> --repo <owner>/<repo> --body "$COMMENT"

Resolve Threads

Threads are resolved by the reviewer — do not attempt to resolve them.

Prerequisites: All fixes applied, tests passing, replies posted.

Step 6A: Commit

Stage and commit all changes:

git add -A
git commit -m "fix(review): address PR feedback

- <summary of changes made>"

If no files were changed (all comments were pushed back, clarified, or acknowledged), skip the commit and push steps.

Step 6B: Push

git push origin <headRefName>

If the push fails (e.g., sandbox network restriction, SSH remote):

1. Display the exact push command to the user
2. Explain that the sandbox may be blocking the push
3. Ask the user to run the push command manually outside Claude Code
4. Wait for user confirmation before proceeding

Step 6C: Re-request Review

Re-request review from the reviewers who left comments:

gh pr edit <number> --repo <owner>/<repo> --add-reviewer <reviewer-login>

Run once per reviewer who left actionable comments.

Step 6D: Report Summary

Present a final summary to the user:

## Review Addressed

PR #<number>: <title>

- **Fixed**: N comments
- **Pushed back**: N comments
- **Clarified**: N comments
- **Acknowledged**: N comments

Changes committed and pushed. Review re-requested from: <reviewer list>