JesusFilm/core / .cursor/skills/handle-pr-review
handle-pr-review
UnverifiedFetches PR review comments, triages them (fix, challenge, or skip), applies holistic fixes, resolves threads, and posts a summary. Use when the user asks to check review feedback, address PR comments, fix review issues, or handle review feedback.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
SKILL.md
View on GitHub---
name: handle-pr-review
description: Fetches PR review comments, triages them (fix, challenge, or skip), applies holistic fixes, resolves threads, and posts a summary. Use when the user asks to check review feedback, address PR comments, fix review issues, or handle review feedback.
---
# Handle PR Review Feedback
<!-- sync: simplified subset of .claude/commands/handle-pr-review.md (canonical). Keep the summary comment step aligned. -->
When the user asks to check or fix review feedback on a PR (e.g. on JesusFilm/core):
## 1. Identify PR
From context (branch, issue number) or ask. Prefer looking up via `gh pr view --json number,url` from the current branch. Fall back to `gh api` by head branch or listing PRs.
## 2. Fetch unresolved threads (GraphQL)
Use GraphQL to get review threads **with thread IDs** (needed later to resolve them). REST does not expose `isResolved` or thread IDs.
```bash
gh api graphql -f query='
query($owner:String!,$repo:String!,$pr:Int!) {
repository(owner:$owner,name:$repo) {
pullRequest(number:$pr) {
reviewThreads(first:100) {
nodes {
id
isResolved
comments(first:20) {
nodes { id body author { login } path line createdAt }
}
}
}
}
}
}' -f owner=OWNER -f repo=REPO -F pr=NUMBER
```
Filter to `isResolved === false`. Collect every comment per thread together — thread context matters.
> **Pagination**: The query above fetches the first 100 threads and 20 comments each. For large PRs that exceed these limits, paginate using `pageInfo { hasNextPage endCursor }` and pass `after: endCursor` in follow-up queries. Nested pagination (threads × comments) requires custom looping — `gh api graphql --paginate` only handles a single connection.
## 3. Triage — classify each thread
Before writing any code, read **all** unresolved threads and the surrounding source code, then classify each into one of:
| Category | When | Action |
|---|---|---|
| **Fix** | Comment is correct and pragmatic | Plan the code change |
| **Challenge** | Comment is wrong, illogical, overly pedantic, contradicts project conventions, or would make the code worse | Draft a respectful reply explaining why (with evidence) |
| **Skip** | Marked "nit", "optional", "minor", or already resolved by another fix | Note it; no action unless user asks |
**How to challenge well:**
- Be respectful but direct. Cite project conventions, existing patterns, or technical reasoning.
- If the suggestion is partially valid, acknowledge what's useful and explain what you'd keep/change.
- Example: _"This pattern is consistent with how we handle X in `api-journeys/src/...`. Changing it here would diverge from the established convention without clear benefit."_
Present the triage to the user for confirmation before proceeding. Format:
```markdown
## Triage
**Will fix:**
- Thread 1: [summary] → [planned change]
- Thread 3: [summary] → [planned change]
**Will challenge:**
- Thread 2: [summary] → [draft reply]
**Will skip:**
- Thread 4: [summary] — marked optional
```
## 4. Analyse holistically before changing code
**Critical: do not fix comments one-by-one in isolation.**
- Read all files touched by "Fix" threads. Understand the broader context.
- Identify dependencies between comments (e.g. a rename in file A affects an import in file B).
- Plan all changes as a cohesive set — the combined diff should leave the code in a clean, consistent state.
- If fixing one comment conflicts with another, flag it to the user.
## 5. Apply fixes
- Make all planned changes.
- One commit per logical change (conventional: `fix:`, `refactor:`, `chore:`). Group related changes into a single commit rather than one commit per comment.
- Run lint/type-check on affected projects before committing: `npx nx run-many -t lint,type-check --projects=<affected>`.
## 6. Push
`git push origin HEAD` (or `git push --set-upstream origin HEAD` if needed). Do not use `--force`; if unavoidable, use `--force-with-lease`.
## 7. Resolve fixed threads (GraphQL)
For each thread that was fixed, resolve it:
```bash
gh api graphql -f query='
mutation($threadId:ID!) {
resolveReviewThread(input:{threadId:$threadId}) {
thread { id isResolved }
}
}' -f threadId=THREAD_ID
```
Do **not** resolve threads that were challenged or skipped.
## 8. Post challenge replies
For each "Challenge" thread, reply inline on the thread via `gh api`:
```bash
gh api repos/OWNER/REPO/pulls/PR/comments/COMMENT_ID/replies \
-f body="Your reply here"
```
Or if the thread is a top-level review comment, fall back to a PR-level comment:
```bash
gh pr comment PR_NUMBER --body "Your reply here"
```
## 9. Post summary comment
<!-- sync: keep "Post summary comment" aligned with the canonical version in .claude/commands/handle-pr-review.md -->
Add a PR comment summarising everything. **Resolve the commit SHA first** — do not rely on shell variable expansion inside heredocs:
```bash
COMMIT_SHA=$(git rev-parse --short HEAD)
gh pr comment NUMBER --body "## Review feedback addressed ($COMMIT_SHA)
**Fixed:**
- \`src/api.ts:42\` — [brief change description]
**Challenged:**
- \`src/util.ts:30\` — [brief reasoning — see inline reply]
**Skipped (optional/nit):**
- [thread summary] — [reason]
"
```
> **Important:** Do **not** use `<<'EOF'` (single-quoted heredoc) — it prevents
> shell variable expansion and renders `$COMMIT_SHA` as a literal string.
> Use `gh pr comment --body "..."` with double-quoted strings or unquoted heredocs
> (`<<EOF`) so that `$COMMIT_SHA` is interpolated.
## Notes
- **Never fix blindly** — every comment deserves critical evaluation. Reviewers can be wrong; the goal is the best code, not maximum compliance.
- **Thread context matters** — read the full thread conversation, not just the last comment. Earlier messages may contain context, agreements, or clarifications.
- **Resolved threads**: skip entirely; do not re-open.
- **CodeRabbit / CodeQL**: treat automated comments the same way — triage, don't auto-accept. Bots can produce false positives or suggestions that conflict with project style.
- If PR number is unknown: first try `gh pr view --json number` from the current branch; fall back to `gh api` by head branch.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |