dkarter/dotfiles/pr-review

PR Review + Commenting

Workflow

1. Gather context

• Identify PR number or current branch; use gh pr view --json number,title,url,baseRefName,headRefName.
• For stacked PRs or unknown base, infer it via gh pr view --json baseRefName on the target PR or by checking the branch's upstream/fork-point.
• Get base comparison: git diff --name-only <base>...HEAD and git diff <base>...HEAD.
• Read plan/spec files mentioned by the user before judging alignment.
• Check repo guidance (AGENTS.md, CLAUDE.md, rules/*) for conventions.

1. Analyze changes

• Review all changed files, not just the latest commit.
• Verify correctness, best practices for the project's frameworks/tooling, tests, and plan/spec requirements.
• Verify clean architecture, good abstractions and adherence to project conventions
• Note gaps: missing features, mismatches with plan/ticket/requirments, unused deps, unhandled edge cases, missing tests, or naming/structure issues.

1. Draft review summary

• Write a concise summary (what changed, what aligns, what is missing).
• Call out required fixes separately from optional improvements.
• If asked, write summary to tmp/reviews.md with sections:
• Summary
• Plan Alignment
• Changes Needed
• Tests

1. Leave PR line comments (if requested). The user may want to review these before you post them, so don't publish those yet, keep them as part of a pending review

• Use gh api to create a pending review with line comments (omit event to keep it pending):
• gh api repos/{owner}/{repo}/pulls/{number}/reviews -f body='...' -F 'comments[][path]=<file>' -F 'comments[][line]=<line>' -F 'comments[][side]=RIGHT' -f 'comments[][body]=...'
• You can also create a pending review with only -f body=... (no line comments).
• GitHub allows only one pending review per user; batch comments in the initial create call or delete/recreate.
• Avoid gh pr review --comment for drafts since it publishes immediately.
• Prefer commenting on the exact line in the diff for each issue that needs a change.
• Keep comments specific, actionable, and reference the plan/spec/documentation if relevant.

Commenting Tips

• Use integer line numbers from the diff (RIGHT side for new code).
• Avoid over-commenting; only flag changes needed or high-value improvements.
• For plan mismatches, cite the plan file and describe the missing requirement.

Output Style

• Keep review summaries concise and scan-friendly.
• Use file path references with inline code.
• Separate required fixes from suggestions.