# Goravel Review Comments

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

- Skill: `goravel/goravel-review-comments` (Agent Skill)
- Install (CLI): `npx skillmds@latest add goravel/goravel-review-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goravel/goravel-review-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: goravel (https://skillmd.com/u/goravel)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goravel/goravel-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)**
   ```bash
   # 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**
   ```bash
   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**
   ```bash
   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.

9. **Commit the staged changes** if any code changed:
   ```bash
   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`.

10. **Push the committed branch** after the commit succeeds:
   ```bash
   git push
   ```
   If the branch has no upstream, use:
   ```bash
   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):
   ```bash
   gh api graphql -f query='
     mutation {
       resolveReviewThread(input: {threadId: "<thread_node_id>"}) {
         thread { isResolved }
       }
     }'
   ```
   To get thread node IDs (type `PRRT_...`, not comment IDs):
   ```bash
   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.