gh-openshift-eng-ai-helpers-plugins-utils/commands/address-reviews.md

description, argument-hint

description	argument-hint
Fetch and address all PR review comments	PR number (optional - uses current branch if omitted)

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

  1. Review changes: git diff

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

     • Identify which commit the changes relate to

  3. 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

  4. Create and push commit:

     • 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

• 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

Arguments:

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