review-pr

name	review-pr
description	Handle CodeRabbit and Codex review comments on a GitHub PR. Fetches the PR, investigates each comment against the codebase, discusses validity with the user, batches valid fixes, and guides through push and reply steps.
allowed-tools	Read, Grep, Glob, Bash
argument-hint	<pr-url-or-number>

PR Review Workflow

Handle review comments (CodeRabbit, Codex, human reviewers) on a GitHub pull request.

Arguments

• $0 — GitHub PR URL or PR number (required)

Steps

1. Fetch and Checkout

git fetch origin
gh pr checkout $0

Always fetch first — automated tools may have pushed fixes not yet local.

2. Load PR Comments

gh pr view $0 --comments
pr_number=$(gh pr view $0 --json number --jq '.number')
gh api repos/hmislk/hmis/pulls/$pr_number/comments

List all review comments. Group them by file/topic.

3. Investigate Each Comment

For each comment:

• Read the referenced file and line range with Read
• Search for related patterns with Grep
• Determine if the comment is valid, a false positive, or project-specific intent

Common false positives in this project:

• Null checks where lazy init already handles it (e.g., getBillFinanceDetails())
• Constructor changes — NEVER modify existing constructors (HMIS rule)
• "Fix" for intentional typos like purcahseRate — database compatibility
• Native SQL suggestions when JPQL works fine
• Bootstrap CSS classes when project uses PrimeFaces

4. Present Findings to User

For each comment, report:

• Comment summary
• Your assessment: Valid / False positive / Discuss
• Reasoning with file:line reference

Wait for user confirmation before making any changes.

5. Batch Valid Fixes

Apply all confirmed fixes. Group into one or a few logical commits:

Fix CodeRabbit review comments (#<issue>)

Closes #<issue>

Co-Authored-By: Claude <[e-mail]>

6. Pre-Push Checklist

• persistence.xml uses ${JDBC_DATASOURCE} / ${JDBC_AUDIT_DATASOURCE} — not hardcoded JNDI names
• No credentials or .env files staged
• JSF-only changes do not need compilation

7. Push

git push

Verify CI passes before proceeding.

8. Reply to Existing Reviewer Threads

⚠️ Cardinal rules — read before posting anything:

1. Do NOT create new top-level inline comments on the PR. Each one becomes a thread the author must manually resolve. This is noise.
2. Reply only after fixing (or explicitly dismissing). Bots cannot fix anything — describe action taken, not requested.
   • Valid + fixed → "Fixed in <commit-sha>: <what was changed>"
   • Dismissed → "Dismissed because: <specific reasoning>"
   ⚠️ "Please resolve" wording on a CodeRabbit thread triggers CodeRabbit Chat — it opens a NEW PR (📝 CodeRabbit Chat: Implement requested code changes, branch coderabbitai/chat/<sha>) attempting the fix against a stale snapshot. These auto-PRs often duplicate work the author has already done and have shipped unsafe diffs (e.g. deleted a params.put(...) line on PR #20979). If you accidentally trigger one: close it, delete the branch.
3. Replies go UNDER existing reviewer threads only (/replies endpoint). Never as new top-level comments.
4. Self-review items go in the commit message (or PR description if deferred). Never as new inline comments.
5. ONE re-review request at the end, not per item.

Order: discuss → fix → push → reply to existing threads → one re-review request.

For each existing reviewer comment, post a threaded reply under the parent. The four endpoints are easy to confuse:

Want	Endpoint	Use?
Reply under existing reviewer comment (threaded)	POST /pulls/{pr}/comments/{id}/replies	YES — this is the only legitimate reply form
New standalone inline comment on a line	POST /pulls/{pr}/comments	NO — creates a fresh thread the author must manually resolve
Bundled review	POST /pulls/{pr}/reviews	NO — grouping wrapper, doesn't match how bots post
General PR comment (only genuine PR-wide notes)	POST /issues/{n}/comments	Sparingly — only for actual PR-wide announcements

For self-review items you spot on your own PR — don't post a new inline comment. Fix in the next commit and reference the file:line in the commit message:

refactor(cashier): address self-review items

- PaymentSettlementController.java:117 — add comment on shallow snapshot
- settle_non_cash.xhtml:203 — use lastSettlementBill.institution.name

Find existing comment IDs to reply to:

gh api "repos/hmislk/hmis/pulls/<PR>/comments" \
  --jq '.[] | "\(.id) \(.user.login) \(.path):\(.line // .original_line)"'

Post a threaded reply:

gh api -X POST "repos/hmislk/hmis/pulls/<PR>/comments/<COMMENT_ID>/replies" \
  -f body="Fixed in <commit-sha>: <what was changed>."

Do NOT resolve other reviewers' conversations. CodeRabbit auto-resolves on detection.

Full API recipes and cleanup commands: see Posting PR Comments via gh CLI.

9. Re-Request Review

Click "Re-request review" on the PR page after pushing. Do not rely on reviewers noticing the new push.

10. Post-Merge Cleanup

After merge:

git branch -d <branch-name>

Also confirm "Delete branch" was checked in the GitHub merge dialog.

Reference

Full workflow documentation: developer_docs/git/pr-review-workflow.md