pr-review

PR Review

Overview

Systematically process every review comment on a GitHub PR: classify each as valid (needs a fix) or invalid (needs a justified reply), present a fix plan, get user approval, apply fixes one-by-one, push, post a summary comment, and resolve threads.

Core principle: Every comment gets a deliberate response: a code fix or a written justification. Nothing is silently ignored.

When to Use

• User pastes a PR number/URL and says "review/address/handle the comments"
• User invokes /devtools:pr-review <number-or-url>
• User asks to "respond to PR feedback", "process review", "address review", or "resolve PR threads"

Do NOT use when:

• User only wants a summary of comments (use gh pr view directly)
• The PR has no review comments
• User wants to write a review on someone else's PR (different workflow)

Required Inputs

A PR identifier in one of these forms:

• Number: 123 (working directory must be the correct repo)
• URL: https://github.com/owner/repo/pull/123
• Shorthand: owner/repo#123

If missing, stop and ask before doing anything else.

Workflow

Phase 1 - Gather

1. Verify gh auth status. If it fails, stop and ask the user to run gh auth login.
2. Resolve owner/repo/number from input.
3. Fetch (in parallel where possible):
   • PR metadata: gh pr view <num> --json title,body,headRefName,baseRefName,state,author,files,isDraft
   • Diff: gh pr diff <num>
   • Inline review comments: gh api "repos/{owner}/{repo}/pulls/{num}/comments" --paginate
   • Review summaries: gh api "repos/{owner}/{repo}/pulls/{num}/reviews" --paginate
   • Issue/general comments: gh api "repos/{owner}/{repo}/issues/{num}/comments" --paginate
   • Review threads with IDs (needed to resolve later; REST does not expose thread IDs):

     gh api graphql -f query='query($owner:String!,$repo:String!,$num:Int!){
       repository(owner:$owner,name:$repo){
         pullRequest(number:$num){
           reviewThreads(first:100){
             nodes{ id isResolved isOutdated comments(first:50){
               nodes{ id databaseId body path line author{login} }
             }}
           }
         }
       }
     }' -F owner=OWNER -F repo=REPO -F num=NUM
     

4. Filter out: already-resolved threads, comments from the PR author themselves, and pure status chatter ("LGTM", emoji-only). Keep all substantive feedback including bot findings.

Phase 2 - Analyze (one comment at a time)

For each unresolved comment, with the file open at the cited line:

1. Read enough context above/below to actually understand.
2. Cross-check against the diff and current branch state.
3. Classify:
   • VALID - reviewer is right. Draft the exact fix: file, lines, before/after, rationale.
   • INVALID - reviewer is mistaken (already fixed, misreading, out of scope, conflicts with explicit requirement). Draft a short evidence-based reply.
   • NEEDS USER INPUT - judgment call (architectural trade-off, scope, conflicting reviewers). Note the question plus 2-3 options.

Track each item with: thread ID, comment ID (databaseId for replies), author, file:line, original text, classification, planned action.

Phase 3 - Present Plan (GATE)

Output a single comprehensive report:

• Counts: total / valid / invalid / needs-input / skipped
• For each VALID: comment quote -> planned fix (file, change description, optional diff snippet)
• For each INVALID: comment quote -> drafted reply text
• For each NEEDS INPUT: comment quote -> the decision and options

Then:

1. Ask the user to resolve every NEEDS-INPUT item.
2. Ask for explicit approval ("approve" / "skip these / change that").

Do NOT modify code or post anything before approval.

Phase 4 - Execute

After approval, process items in order:

1. VALID:
   • Apply the fix with normal repo editing tools.
   • Run obvious affected tests/linters; never claim success without running them.
   • Stage the change.
2. INVALID: Post the drafted reply threaded to the original comment:

   gh api "repos/{owner}/{repo}/pulls/{num}/comments" \
     -f body="<reply text>" -F in_reply_to=<comment_databaseId>
   

3. Collect thread IDs for resolution after push.

If a fix fails or surfaces new information, stop, report back, and ask before continuing.

Phase 5 - Commit & Push

1. Show the staged diff summary to the user.
2. Commit with a clear message (for example, fix: address PR review comments). Do not add AI co-author trailers unless the repo convention requires it.
3. Push to the PR branch.

Phase 6 - Report & Resolve

1. Post a single summary PR comment:

   gh pr comment <num> --body-file report.md
   

2. Resolve every thread that was acted on (fixed or replied):

   gh api graphql -f query='mutation($id:ID!){
     resolveReviewThread(input:{threadId:$id}){ thread { id isResolved } }
   }' -F id=<threadId>
   

3. Report back to the user: comment URL, fixed count, replied count, resolved-thread count, any deferred items.

Reply Template (Invalid Comments)

Short, evidence-based, non-defensive:

Thanks for taking a look. After re-checking <file:line>, this is actually <observation>:
<specific reason it is not an issue / is intentional / is out of scope>.
Happy to revisit if I am missing context.

Final Report Template

## PR Review Response

Addressed **N** review comments.

### Fixed (X)
- @reviewer - `file.ts:42` - <one-line summary> (<commit-sha>)

### Replied (Y)
- @reviewer - `file.ts:88` - <why we disagreed, one line>

### Deferred (Z)
- @reviewer - `file.ts:120` - <reason; tracked in #issue>

All addressed threads have been resolved.

Common Mistakes

Mistake	Fix
Editing code before user approved the plan	Phase 3 is a hard gate. No edits until "go".
Claiming tests pass without running them	Run the command. Cite the output.
Resolving threads before the fix is pushed	Resolve only after git push succeeds.
Dismissive replies to invalid comments	Cite file/line evidence. Polite, specific, brief.
Bundling unrelated fixes into one commit	One commit scope = the review. No drive-by changes.
Using REST to find thread IDs	REST /comments has no thread ID. Use GraphQL reviewThreads.
Silently skipping a comment	Every unresolved, non-author comment must be classified.
Replying to outdated/obsolete threads	Mark isOutdated ones as skipped with a note in the report.

Red Flags - STOP

• About to edit code before user approved the plan
• About to call resolveReviewThread before the fix is pushed
• Drafting a reply that says "you are wrong" without citing evidence
• Skipping a comment because "it is minor"
• Posting the final report before all VALID items are actually fixed and pushed

Quick Command Reference

# Resolve owner/repo from a URL: parse https://github.com/OWNER/REPO/pull/NUM

# Auth
gh auth status

# PR + diff
gh pr view <num> --json title,headRefName,baseRefName,author,files,isDraft
gh pr diff <num>

# Comments
gh api "repos/{owner}/{repo}/pulls/{num}/comments" --paginate
gh api "repos/{owner}/{repo}/pulls/{num}/reviews" --paginate
gh api "repos/{owner}/{repo}/issues/{num}/comments" --paginate

# Reply to an inline comment (threaded)
gh api "repos/{owner}/{repo}/pulls/{num}/comments" \
  -f body="..." -F in_reply_to=<comment_databaseId>

# Post the final summary
gh pr comment <num> --body-file report.md

# Resolve a thread (GraphQL; needs thread ID from reviewThreads query)
gh api graphql -f query='mutation($id:ID!){
  resolveReviewThread(input:{threadId:$id}){ thread { id isResolved } }
}' -F id=<threadId>