/address-reviews

Name

utils:address-reviews

Synopsis

/utils:address-reviews [PR number (optional - uses current branch if omitted)]

Description

This command automates the process of addressing PR review comments by fetching all comments from a pull request, categorizing them by priority (blocking, change requests, questions, suggestions), and systematically addressing each one. It intelligently filters out outdated comments, bot-generated content, and oversized responses to optimize context usage. The command handles code changes, posts replies to reviewers, and maintains a clean git history by amending relevant commits rather than creating unnecessary new ones.

Implementation

Step 0: Checkout the PR Branch

1. Determine PR number: Use $ARGUMENTS if provided, otherwise gh pr list --head <current-branch>
2. Checkout: Use gh pr checkout <PR_NUMBER> if not already on the branch, then git pull
3. Verify clean working tree: Run git status. If uncommitted changes exist, ask user how to proceed

Step 1: Fetch PR Context

1. Fetch PR metadata with selective filtering:

   a. First pass - Get metadata only (IDs, authors, lengths, URLs):

   # Get issue comments (general PR comments - main conversation)
   gh pr view <PR_NUMBER> --json comments --jq '.comments | map({
     id,
     author: .author.login,
     length: (.body | length),
     url,
     createdAt,
     type: "issue_comment"
   })'
   
   # Get reviews (need REST API for numeric IDs)
   gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews --jq 'map({
     id,
     author: .user.login,
     length: (.body | length),
     state,
     submitted_at,
     type: "review"
   })'
   
   # Get review comments (inline code comments)
   gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments --jq 'map({
     id,
     author: .user.login,
     length: (.body | length),
     path,
     line,
     created_at,
     type: "review_comment"
   })'
   

   b. Apply filtering logic (DO NOT fetch full body yet):

   • Filter out: line == null (outdated review comments)
   • Filter out: length > 5000
   • Filter out: CI/automation bots author in ["openshift-ci-robot", "openshift-ci"] (keep coderabbitai for code review insights)
   • Keep track of filtered items and stats for reporting

   c. Second pass - Fetch ONLY essential fields for kept items:

   # For issue comments - fetch only body and minimal metadata:
   gh api repos/{owner}/{repo}/issues/comments/<comment_id> --jq '{id, body, user: .user.login, created_at, url}'
   
   # For reviews - fetch only body and state:
   gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/reviews/<review_id> --jq '{id, body, user: .user.login, state, submitted_at}'
   
   # For review comments - fetch only body and code context:
   gh api repos/{owner}/{repo}/pulls/comments/<comment_id> --jq '{id, body, user: .user.login, path, position, diff_hunk, created_at}'
   

   Note: Using --jq to select only needed fields minimizes context usage. Avoid fetching full API responses with all metadata.

   d. Log filtering results:

   ℹ️  Fetched N/M comments (filtered out K large/bot comments saving ~X chars)
   

2. Fetch commit messages: gh pr view <PR_NUMBER> --json commits -q '.commits[] | "\(.messageHeadline)\n\n\(.messageBody)"'

3. Store ONLY the kept (filtered) comments for analysis

Step 2: Categorize and Prioritize Comments

Note: Most filtering already happened in Step 1 to save context window space.

1. Additional filtering (for remaining fetched comments):

   • Already resolved comments
   • Pure acknowledgments ("LGTM", "Thanks!", etc.)

2. Categorize:

   • BLOCKING: Critical changes (security, bugs, breaking issues)
   • CHANGE_REQUEST: Code improvements or refactoring
   • QUESTION: Requests for clarification
   • SUGGESTION: Optional improvements (nits, non-critical)

3. Group by context: Group by file, then by proximity (within 10 lines)

4. Prioritize: BLOCKING → CHANGE_REQUEST → QUESTION → SUGGESTION

5. Present summary: Show counts by category and file groupings, ask user to confirm

Step 3: Address Comments

Grouped Comments

When multiple comments relate to the same concern/fix:

• Make the code change once
• Reply to EACH comment individually (don't copy-paste, tailor each reply)
• Optional reference: Done. (Also addresses feedback from @user)

Code Change Requests

a. Validate: Thoroughly analyze if the change is valid and fixes an issue or improves code. Don't be afraid to reject the change if it doesn't make sense.

b. If requested change is valid:

• Plan and implement changes

• Commit and Push (ALL sub-steps are MANDATORY — do not skip any)

  1. Review changes: git diff

  2. Sync with remote first: git pull --rebase origin <branch> to ensure local branch is up to date. If the branch is behind or diverged, you MUST rebase before committing.

  3. Analyze commit structure: git log --oneline origin/main..HEAD

     • Identify which commit the changes relate to

  4. Commit strategy:

     DEFAULT: Amend the relevant commit

     • ✅ AMEND: Review fixes, bug fixes, style improvements, refactoring, docs, tests within PR scope
     • ❌ NEW COMMIT: Only for substantial new features beyond PR's original scope
     • When unsure: Amend (keep git history clean)
     • Multiple commits: Use git rebase -i origin/main to amend the specific relevant commit

  5. Create commit AND push (both required):

     • Follow Conventional Commits format
     • Always include body explaining "why"
     • Amend: git commit --amend --no-edit && git push --force-with-lease (or update message if scope changed)
     • New commit: Standard commit with message, then git push
     • ⚠️ A commit without a push is incomplete. You MUST push.

  6. Verify push succeeded (MANDATORY before replying):

     • Run git log -1 --format='%H' locally and git ls-remote origin <branch> to confirm the remote has your commit
     • If they differ: The push failed or was never executed. Do NOT post a "Done" reply. Diagnose and retry, or report the failure to the user.
     • If uncommitted changes remain (git status): The commit failed. Fix it first.
     • ⚠️ NEVER post a "Done" or "Fixed" reply unless the push is verified on the remote. Posting false claims of completion erodes reviewer trust and wastes human reviewers' time.

• Concise Reply template: Done. [1-line what changed]. [Optional 1-line why]

  • Max 2 sentences + attribution footer

• Post reply:

  gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments/<comment_id>/replies -f body="<reply>"
  

  If fails: gh pr comment <PR_NUMBER> --body="@<author> <reply>"

c. If declining change:

• Reply with technical explanation (3-5 sentences):
  • Why current implementation is correct
  • Specific reasoning with file:line references
• Use same posting method as (b)

d. If unsure: Ask user for clarification

Clarification Requests

• Provide clear, detailed answer (2-4 sentences)
• Include file:line references when applicable
• Post using same method as code changes

Informational Comments

• No action unless response is courteous

All replies must include: ---\n*AI-assisted response via Claude Code*

Step 4: Summary

Show user:

• Total comments found (raw count from API)
• Comments filtered out (with reason: outdated/large/bot-generated)
• Comments addressed with code changes
• Comments replied to
• Comments requiring user input

Guidelines

• Be thorough but efficient
• Maintain professional tone in all replies
• Prioritize code quality over quick fixes
• Ensure code builds and passes tests after changes
• When in doubt, ask the user
• Use TodoWrite to track progress through multiple comments

Duplicate Prevention

Before posting ANY reply, verify you haven't already responded:

CHECK_REPLIED="${CLAUDE_PLUGIN_ROOT}/scripts/check_replied.py"
if [ ! -f "$CHECK_REPLIED" ]; then
  CHECK_REPLIED=$(find ~/.claude/plugins -type f -path "*/utils/scripts/check_replied.py" 2>/dev/null | sort | head -1)
fi
if [ -z "$CHECK_REPLIED" ] || [ ! -f "$CHECK_REPLIED" ]; then echo "ERROR: check_replied.py not found" >&2; exit 2; fi
python3 "$CHECK_REPLIED" <owner> <repo> <pr_number> <comment_id> --type <type>

Where <type> is one of: issue_comment, review_thread, or review_comment

If the script returns exit code 1: Skip that comment - you've already replied. If the script returns exit code 2: The check failed - do NOT post a reply. Investigate and fix the issue before proceeding.

Response Rules

1. One response per feedback: For each piece of feedback, choose ONE response mechanism:

   • Inline review comments → reply inline only
   • General PR comments → reply as general comment only
   • NEVER respond to the same feedback via both mechanisms

2. Code changes require explicit request: Only modify code when the reviewer explicitly asks using imperative language like "change", "fix", "remove", "update", "add". For questions, clarifications, or observations - reply with explanation only, do not change code.

3. Check before acting: If a comment is phrased as a question ("Why did you...?", "What about...?"), provide an explanation. Only make code changes for direct requests ("Please change...", "This should be...", "Remove this...").

Arguments:

• $1: [PR number to address reviews (optional - uses current branch if omitted)]