How do I address PR review comments?

How do I read open review comments on the current PR, apply the requested fixes, and close the review threads?

To find PRs with unattended reviews in the first place, run:

./compass.sh review pending                    # last 24h, all states
./compass.sh review pending --since 7d

Results are triaged: 🛑 merged/closed PRs whose review feedback was never addressed (not fine — recover the feedback), ⚠ open PRs that need a round here, ✅ open PRs being worked in another worktree (fine — handle the round in that environment, never from here).

Then, for each PR that needs a round in this checkout:

1. Sync with main first. Before touching any code, ensure your branch is up to date:

   ./compass.sh pr sync
   

   On conflicts the command stops where git stops and lists the ways out. Addressing comments on a stale branch risks rebase conflicts later and merge noise; sync first, then address — never the other way around.

2. Read the open comments:

   ./compass.sh review list <pr_number>            # id, file, line, preview
   ./compass.sh review list <pr_number> --detail   # full bodies
   

   The output has two sections: line-level threads (the ones that take replies and resolution) and conversation-level comments — review summaries and bot banners. --format json for machine consumption.

3. Decide on each comment. For every comment, make an explicit accept/decline decision before touching any code:
   • Accept — the comment identifies a real problem or improvement. Apply the fix.
   • Decline — the suggestion conflicts with an existing convention, creates inconsistency, or is otherwise not applicable. Do not silently ignore it; you must still reply (see step 4).

4. Apply fixes per accepted comment. One logical fix per commit:

   git add <modified-files>
   git commit -m "[component] Address review comment: <brief description>"
   

   Never amend existing commits — that destroys the review history and confuses the reviewer.

5. Push the batch when all accepted comments in the round are fixed:

   git push
   

6. Reply to every comment — accepted or declined — with a clear explanation. This is mandatory, not optional.

   • Accepted: state what was changed and in which commit.
   • Declined: state why (convention conflict, semantic difference, etc.). Keep it factual; reviewers need to understand the reasoning.

   ./compass.sh review reply <pr_number> <comment_id> \
     "Fixed in commit <sha> — <brief description>."
   # or, for a declined comment:
   ./compass.sh review reply <pr_number> <comment_id> \
     "Not changed. <reason>."
   

   The comment id comes from compass review list.

7. Resolve the review threads — only after every comment has its reply:

   ./compass.sh review resolve <pr_number> --dry-run   # preview
   ./compass.sh review resolve <pr_number>             # resolve all
   

8. Record the review round in the story or task doc. Add or update the * Review section of the task's .org file with a summary table:

   | # | Comment summary         | File              | Decision | Notes                          |
   |---+-------------------------+-------------------+----------+--------------------------------|
   | 1 | Expand .gitignore       | .gitignore        | Applied  | Added .aux/.log/.out/.toc      |
   | 2 | Use CMAKE_CURRENT_...   | CMakeLists.txt    | Declined | All other targets use CMAKE_SOURCE_DIR |
   | 3 | Relative PDF link       | user_manual.org   | Applied  | Changed to user_manual.pdf     |
   

   For stories without tasks, record in story.org. The PR URL is tracked in the * PRs table there (see How do I create a PR? step 4). Commit the updated doc in the same push or as a follow-up commit on the feature branch.

• One commit per logical fix. Squash later if you want, but never on a PR under active review.
• Reply + resolve are mandatory. Every comment — accepted or declined — must have a reply and a resolved thread before merge. The PR dashboard shows unresolved threads as outstanding work.
• Record in the task. The * Review section is the durable record of what reviewers flagged and what was done. Future readers should not need to open GitHub to understand the review history.

Bare gh CLI; no wrapper.

Manual. PR Shepherd automates the loop around this recipe.

• How do I monitor a PR until green? — the outer loop.
• How do I fix a failing CI check? — the sibling failure mode.
• PR Manager.