goravel-review-comments

name	goravel-review-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

1. Fetch all comments (both pages)

   # Preferred: gets all review threads (incl. inline comments) via GraphQL, not paginated
   gh pr view {pr_number} --json reviewThreads --jq '[.reviewThreads[] | select(.isResolved | not)]'
   # Or combined with top-level comments:
   gh pr view {pr_number} --json comments,reviewThreads --jq '{comments: .comments, unresolvedThreads: [.reviewThreads[] | select(.isResolved | not)]}'
   # For inline review comments via REST API — MUST use --paginate or you will miss pages:
   gh api --paginate repos/{owner}/{repo}/pulls/{pr_number}/comments
   

   Critical: GitHub REST API endpoints return at most 30 items per page. gh api without --paginate only returns page 1 and silently drops the rest. Always pass --paginate to walk every page. gh pr view --json uses GraphQL internally and is not affected by REST pagination.

   Ignore resolved review threads and resolved comments. Only triage unresolved feedback that still needs action. If you use the inline comment endpoint, cross-check each comment against reviewThreads and skip any comment whose thread is already resolved.

2. Inspect the worktree before editing

   git status --short
   

   Note any pre-existing changes. Do not stage, commit, revert, or overwrite unrelated user changes.

3. Triage each unresolved comment using the decision tree above.

4. Group related changes — if multiple comments touch the same file or function, batch the edits together before replying.

5. 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.

6. Apply required code changes for comments that identify valid issues.

7. Run focused verification for changed code. Follow skills/goravel-testing/SKILL.md: prefer package- or test-specific commands, and do not run go test ./... unless the user explicitly asks for all tests.

8. Review and stage only the intended changes

git push

If the branch has no upstream, use:

git push -u origin HEAD

11. Reply to changed comments after pushing, with a concise summary of the fix that landed.

12. 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.
• Resolved threads are out of scope for this workflow. Do not re-triage, re-answer, or reopen resolved feedback unless the user explicitly asks you to.
• 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.