| name | solve-pr-comments |
| description | Workflow for addressing pull request review comments. Covers when to change code, when to push back on incorrect feedback, and when to answer questions without modifying code. Use this skill whenever the user asks to resolve, address, or respond to PR review comments.
|
Solve PR Comments
A PR review comment is not an order — it is input. Your job is to evaluate
each comment with the same rigor you apply to code, then take the right action:
change, decline, or answer.
Decision tree
For every comment, determine which category it falls into before acting:
Is the comment technically correct?
├── No → Decline and explain in a reply; do not resolve the thread
└── Yes → Is it a question or a request for clarification?
├── Yes → Answer in a reply; do not resolve the thread
└── No → Apply the change, test, commit, push, reply, then resolve the thread
1. Apply the change
Change code when the comment identifies a real problem: a bug, a violation of
project conventions, a clarity issue, or a missed edge case.
Rules:
- Apply the minimal fix that addresses the concern. Do not refactor unrelated code.
- Run focused tests that cover the changed behavior before committing.
- Commit the code changes, then push the updated branch before replying to the comment.
- After pushing, reply with a one-sentence summary of what changed, then resolve the thread.
- If the fix is non-trivial, briefly explain the approach taken.
2. Decline and explain
Not every comment is correct. Push back when:
- The suggestion introduces a bug or regression.
- The suggestion contradicts an established pattern in this codebase (point to the location).
- The suggestion is a matter of style preference with no objective benefit, and the existing code
already follows a consistent convention.
- The suggestion is based on a misunderstanding of the code's intent.
Rules:
- Always reply with a clear, respectful explanation. Never silently ignore a comment.
- State the specific reason: wrong behavior, conflicts with
file:line, performance trade-off, etc.
- If appropriate, offer a counter-proposal.
- Do not change the code to pacify a reviewer when you believe the original is correct.
- Do not resolve the thread unless the user explicitly asks you to.
Example reply:
This change would bypass the nil-check on line 42 and cause a panic when the
cache is cold. The current guard is intentional — I'd rather keep it as-is.
Happy to add a comment if the intent is unclear.
3. Answer the question
Some comments are genuine questions: "Why did you do X?", "What does this return
when Y?", "Is this thread-safe?". These need an answer, not a code change.
Rules:
- Reply with a direct answer.
- Do not resolve the thread unless the user explicitly asks you to.
- If the question reveals that the code is genuinely confusing, consider adding a
comment or renaming — but only if it actually improves clarity, not just to
satisfy the reviewer.
- Never change code solely to signal that you read the comment.
Workflow
-
Fetch comments
gh pr view {pr_number} --json comments,reviewThreads
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments
-
Inspect the worktree before editing
git status --short
Note any pre-existing changes. Do not stage, commit, revert, or overwrite
unrelated user changes.
-
Triage each comment using the decision tree above.
-
Group related changes — if multiple comments touch the same file or
function, batch the edits together before replying.
-
Handle reply-only comments — if a comment does not require a code change,
or it is a question, reply directly and do not resolve the thread.
-
Apply required code changes for comments that identify valid issues.
-
Run focused verification for changed code. Follow .agents/prompts/tests.md:
prefer package- or test-specific commands, and do not run go test ./...
unless the user explicitly asks for all tests.
-
Review and stage only the intended changes
git diff
git status --short
git add <changed-files>
If a file contains both your edits and unrelated pre-existing edits, stage
only the relevant hunks. Do not include generated mocks unless they were
regenerated by the proper project command.
-
Commit the staged changes if any code changed:
git commit -m "fix: address PR review comments"
Use a concise message that matches the actual change. If there is nothing
staged, stop and explain why there is no commit instead of continuing to
git push.
-
Push the committed branch after the commit succeeds:
git push
If the branch has no upstream, use:
git push -u origin HEAD
-
Reply to changed comments after pushing, with a concise summary of the
fix that landed.
-
Mark changed threads resolved after replying, using the GitHub GraphQL
resolveReviewThread mutation (requires the thread node ID):
gh api graphql -f query='
mutation {
resolveReviewThread(input: {threadId: "<thread_node_id>"}) {
thread { isResolved }
}
}'
To get thread node IDs (type PRRT_..., not comment IDs):
gh pr view {pr_number} --json reviewThreads --jq '.reviewThreads[].id'
Alternatively, resolve threads directly in the GitHub UI.
Guardrails
- Never mark a comment as resolved unless you applied a code change for it,
committed and pushed the branch, and replied with what changed.
- Never leave valid code-change comments only in the local worktree. If code
changed, the normal terminal state is: tests run, changes committed, branch
pushed, comments replied to, and changed threads resolved.
- If commit or push fails, do not resolve the thread. Report the exact blocker
and leave the branch in a reviewable state.
- Do not resolve question-only or no-change comments after replying unless the
user explicitly asks you to.
- Never apply a change you believe is wrong just to close a thread.
- Never reply with vague acknowledgements ("Sure!", "Done") — every reply
must state what was done or why nothing was done.
- Never open a PR comment thread with a different concern from the original;
raise separate issues separately.
