Handle a PR review round

Handle one complete review round: sync with main, read all review comments, decide accept/decline per comment, apply fixes bundled with the round's * Review table update, push once, reply to every comment, resolve threads, and — if this was the final round — merge immediately on green CI. Task/story bookkeeping is not part of this runbook: it happens before the PR exists (see Work a task through to merged PR), so no bookkeeping-only commit should ever follow a review round.

• PR is open with review comments.
• You are on the feature branch.
• SSH_AUTH_SOCK is exported (see SSH memory).

In execution order:

1. Gate: confirm there is a round to handle. compass review list <N> --detail before anything else:

   • No comments yet, or the reviewer is still running ("Working on review…" placeholders) → stop and wait; do not sync.
   • Every comment already has a reply and all threads are resolved → the round is done; stop.

   Only proceed when unaddressed comments exist. Syncing first churns CI and forces a force-push even when there is nothing to do.

2. Sync with main. compass pr sync — fetch, rebase, and report; on conflicts it stops with the conflicted files and the ways out. Never address review comments on a stale branch.

3. Check CI status. Before reading comments, inspect the current CI state:

   compass pr checks <N>
   

   • If any check is failing, identify and fix the root cause first — as a separate commit — before looking at review comments. A CI failure may explain or supersede some review comments.
   • If checks are pending / running, notify the user and proceed to step 3; CI will be re-verified after fixes are pushed (step 7).
   • If CI is green, proceed immediately.
4. Read the comments. compass review list <N> --detail — line-level threads and conversation-level comments/review summaries in one view. See How do I address PR review comments? step 1.
5. Decide per comment. For each comment, make an explicit accept/decline decision. Never silently ignore a comment.
6. Apply fixes. One commit per logical fix. Never amend commits on a branch under review. Use commit conventions. Build and run tests locally before pushing — the only local verification this round gets. Update the task's * Review table for this round (what step 10 used to do as a separate step) now, so it lands in the same commit set as the fixes — never as a later, code-free commit.
7. Push. git push — fixes and the * Review table update together.
8. Verify CI is green. Re-run compass pr checks <N> (or --watch to poll) and wait until no checks are pending. If any check fails, fix, commit, push, and repeat this step. Do not reply to review comments while CI is red.
9. Reply to every comment. Accepted: "Fixed in commit <sha> — <description>." Declined: "Not changed. <reason>." Use compass review reply <N> <comment-id> "<message>" per the recipe.
10. Resolve threads. compass review resolve <N> (--dry-run to preview).

Replying (step 8) and resolving (step 9) are GitHub API calls, not commits — they never trigger CI, so they're safe to do after step 7's green check without starting a new cycle.

1. If this was the final round and the PR delivers the task, merge immediately. Task/story bookkeeping should already be in place from before the PR was raised (see agile-close-task — it runs ahead of pr-raise, not after review). Do not push a bookkeeping commit now: that would force a fresh CI cycle for a change with no code content, on a PR that was already green and approved. Go straight to How do I merge a PR?.

• All CI checks on the PR are green.
• All review comments have replies.
• All threads are resolved.
• Review round is recorded in the task's * Review table, committed together with this round's fixes (not a separate commit).
• Branch is pushed and PR is updated.
• If this was the final round: the PR is merged, with no commits pushed after the last green CI run.

• How do I address PR review comments? — the detailed recipe.
• Work a task through to merged PR — the full task lifecycle including review.
• Runbooks catalogue — all runbooks.