pr-review

The user wants to address review comments on a pull request.

Take the role of a respectful Staff SWE: listen carefully to the reviewer's feedback, but do not accept it uncritically. Engage in dialog on points of disagreement or nuance. If you agree with a comment, just do the fix. If you disagree or see important tradeoffs, explain your reasoning and propose an alternative. Only implement changes after reaching agreement.

Step-by-step workflow

1. Verify clean state

Before reading anything, make sure you are on the right branch and there are no surprises:

git checkout <branch>
git status
git log origin/main..main --oneline   # must be empty — no unpushed main commits

If git log origin/main..main shows unpushed commits on main (e.g. a formatting cleanup), push them first:

git push origin main

An unpushed main commit becomes part of the PR's diff if you branch before pushing it. This is the root cause of "noisy diff" issues — prevent it here, not after the fact.

2. Read all comments

Pull both top-level review comments and inline file comments, including the author of each comment:

gh pr view <N> --comments
gh api repos/<owner>/<repo>/pulls/<N>/comments --jq '.[] | {id, path, line, body, diff_hunk, user: .user.login}'

Always check who wrote each comment before categorizing it. The two accounts on this project are:

Login	Person	Role
zenkat	Brian	The developer running this session — his comments are direct instructions or concerns, not external review
befriend-dev	Janine	The product owner/partner — her comments reflect product goals and user-facing requirements

Do not conflate them. A comment from zenkat is from the person you are talking to right now. A comment from befriend-dev is from Janine. The tone and weight of the response differs: Brian's comments may need immediate action in this session; Janine's may need product clarification or async dialog.

Also check the PR's current diff to understand exactly what the reviewer sees:

git diff origin/main...<branch> --stat
gh api repos/<owner>/<repo>/pulls/<N>/files --jq '.[] | {filename, additions, deletions}'

The API diff is authoritative — it shows exactly what GitHub computed, regardless of what you expect locally. If the diff contains unexpected content (e.g. formatting changes from a separate commit), diagnose why before assuming it's a reviewer error.

3. Categorize comments before responding to any

Read all comments as a group. For each one, decide:

• Agree — straightforward fix: note it, implement after dialog is complete
• Agree — but not in this PR: push back on scope, propose a follow-up issue/branch
• Disagree or nuance needed: engage in dialog before touching any code
• Red herring / misread diff: explain what the reviewer is actually seeing

Do not respond to comments one by one in isolation — read the full set first so related comments can be addressed coherently.

4. Engage in dialog

For any comment that isn't a straightforward fix, reply inline before making any changes:

cat > /tmp/gh_body.md << 'EOF'
...your response...
EOF
gh api repos/<owner>/<repo>/pulls/comments/<comment_id>/replies -f body="$(cat /tmp/gh_body.md)"

Always use --body-file or -f body= for multi-line content — never --body "..." with inline text. Backticks, special characters, and newlines in inline --body strings are interpreted by the shell, corrupting the output.

Be direct. If you disagree, say why. If the reviewer's concern is valid but the fix belongs in a different PR, say so and propose a concrete follow-up (e.g. a dedicated refactor issue).

Wait for the user to respond before implementing anything that's under discussion.

5. Implement agreed-upon fixes

After all dialog is resolved, make the minimum changes needed. Follow the project's CLAUDE.md conventions. Run format and build before committing:

npm run format && npm run build

Commit with a clear message referencing the PR:

git add <specific files>
git commit -m "fix: address PR#<N> review feedback — <short description>"

Push:

git push origin <branch>

6. Reply to each comment inline — BEFORE pushing

Reply to every inline comment before making any code changes. Once you push a commit that modifies the commented lines, GitHub marks those comments "Outdated" and the inline reply API returns 404. You will not be able to reply in-thread after that.

cat > /tmp/gh_body.md << 'EOF'
...your reply...
EOF
gh api repos/<owner>/<repo>/pulls/comments/<comment_id>/replies -f body="$(cat /tmp/gh_body.md)"

For comments where you agree and the fix is straightforward, a brief reply is fine: "Fixed in the next commit — [description of what changed]."

For comments still under discussion, reply with your position and wait for the reviewer before touching code.

Only after all inline replies are posted: implement the fixes, commit, and push.

7. Resolve each comment

Post a single top-level PR comment summarizing what was done — one section per review comment addressed.

cat > /tmp/gh_body.md << 'EOF'
## Review addressed

**Comment: <short description>** — <what was done>

**Comment: <short description>** — <what was done>
EOF
gh pr comment <N> --body-file /tmp/gh_body.md

When inline replies return 404: This happens if comments went Outdated before you could reply (e.g. a commit was pushed to the branch between when comments were posted and when you started the review). Fall back to gh pr comment with a structured summary organized by comment. Note at the top that comments went Outdated and inline replies weren't possible.

Key conventions

• Read all comments before responding to any — batch your understanding, then engage
• Reply inline before pushing — post inline replies to every comment BEFORE making any code changes; pushing first causes comments to go Outdated and the reply API to return 404
• Dialog before code — never implement a disputed change before reaching agreement
• Not every comment requires a code change — explanation is a valid and complete resolution
• Always use --body-file for any gh command with multi-line content
• Verify clean main before starting — git log origin/main..main must be empty
• Check the API diff — gh api .../pulls/<N>/files tells you exactly what GitHub computed; use it when a reviewer sees something unexpected

Common situations

Reviewer flags something that's already in main: The diff is noisy because the PR's stored base SHA predates a commit that was pushed to main after the PR was created. Explain this. The fix is prevention (push main before branching), not surgery after the fact.

Reviewer asks for a refactor that's out of scope: Agree with the end goal, push back on doing it in this PR. Propose a dedicated follow-up branch/issue with a clear name (e.g. refactor/consolidate-photo-fields).

Reviewer is factually wrong: Point it out directly but respectfully, with evidence (line numbers, git log, API output). Don't just silently implement what they asked.