pr-review-plan

You have been invoked as a skill. Execute the steps below immediately. Do not deliberate about whether to respond. Start with Step 1 now.

Plan PR Review

Fetch all review comments from a GitHub PR, read the relevant source code for context, triage each thread, draft short replies, and write everything to a persistent plan artifact. This skill is read-only — it never modifies source files, posts to GitHub, or touches CLAUDE.md.

The plan artifact is the hand-off to /pr-review:pr-review-apply (fix code) and /pr-review:pr-review-post (reply + resolve). The user can edit the plan file directly to adjust triage decisions or draft replies before those skills run.

Prerequisites

• gh CLI authenticated (gh auth status)
• jq installed
• Inside a git repository with a branch that has an associated PR

Step 1: Fetch

FETCH_OUT=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/gh-review-fetch.sh)
# Or with explicit PR number:
FETCH_OUT=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/gh-review-fetch.sh 123)
# Or with explicit repo:
FETCH_OUT=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/gh-review-fetch.sh 123 --repo owner/repo)

REVIEW_JSON=$(echo "$FETCH_OUT" | head -1)

Verify $REVIEW_JSON is a valid file path: test -f "$REVIEW_JSON" || echo "ERROR: fetch failed".

• stdout line 1 = path to JSON file in /tmp, line 2 = counts summary
• The JSON file persists for the session

Parse the JSON into a compact summary with a single command. Do NOT read the raw JSON file directly — it is too large and will waste context. Use this exact command:

python3 -c "
import json, re
data = json.load(open('REVIEW_JSON_PATH'))
print(f\"PR #{data['meta']['pr_number']} on {data['meta']['repo']}\")
print(f\"Fetched: {data['meta']['fetched_at']}\")
print(f\"Threads: {data['meta']['total_inline_threads']} inline, {data['meta']['total_review_summaries']} reviews, {data['meta']['total_conversation_comments']} conversation\")
for fg in data['inline_by_file']:
    print(f\"\n## {fg['file']} ({len(fg['threads'])} threads)\")
    for t in fg['threads']:
        print(f\"  Thread {t['thread_id']} L{t['line_start']}-{t['line_end']} stale={t['position_stale']} suggestion={t['has_suggestion']}\")
        for c in t['comments']:
            body = c['body'][:300].replace('\n',' ')
            m = re.search(r'\x60\x60\x60suggestion(.*?)\x60\x60\x60', c['body'], re.DOTALL)
            if m: body += ' [SUGGESTION: ' + m.group(1).strip()[:150] + ']'
            print(f\"    [{c['user']}]: {body}\")
for rs in data.get('review_summaries',[]):
    if rs.get('body'): print(f\"\nReview ({rs['state']}) by {rs['user']}: {rs['body'][:300].replace(chr(10),' ')}\")
for cc in data.get('conversation_comments',[]):
    if cc.get('body'): print(f\"\nConversation [{cc['user']}]: {cc['body'][:300].replace(chr(10),' ')}\")
"

Replace REVIEW_JSON_PATH with the actual path from the fetch output. This gives you everything you need for triage in one tool call. Do not run additional Python scripts to re-parse the same data.

If the output shows no inline threads, skip to Step 3 (review summaries).

Efficiency target

This skill should complete in roughly 3 + N tool calls where N is the number of files with threads:

• 1 fetch script call
• 1 JSON parse (the Python command above)
• N file reads (one per file group — batch all threads for that file into one Read)
• 1 write for the plan file (or a few small writes if processing incrementally)

If you find yourself running additional Python scripts to re-parse JSON you already have, or reading the raw JSON file, stop — you are over-processing. The parse command above gives you everything you need.

Step 2: Triage inline threads

Process each file group. For each file:

Read source code

Open the file and read the lines around each thread's line_start/line_end. Also read the diff_hunk — it shows the diff context the reviewer saw. You need both the current code and the diff context to judge whether feedback is valid.

Read each file once — batch all threads for that file into a single Read call with enough surrounding context.

Classify each thread

For each thread, evaluate:

Is the feedback valid? Consider:

• Does the comment identify a real bug, missing edge case, or concrete improvement?
• Is the comment outdated? (position_stale: true means the diff has moved — but check if the same issue persists at the current lines)
• Has the author already replied agreeing or disagreeing in the thread?
• Is it a subjective style preference with no functional impact?

Classifications:

• apply_suggestion — has_suggestion: true and the suggested code is correct. Extract the replacement text from the ```suggestion fence in the comment body.
• fix — Valid feedback, no suggestion provided. Describe concretely what the fix should do (e.g., "add a catch clause for SocketTimeoutException on line 24").
• skip_stale — Targets code that has changed and is no longer relevant.
• skip_disagree — Feedback is incorrect or would make the code worse. Explain why.
• skip_style — Pure style preference, no objective improvement. Explain why.
• needs_clarification — Ambiguous, flag for the user.

Check review summaries and conversation comments

Also check review_summaries and conversation_comments for high-level feedback not tied to specific lines: architectural concerns, cross-cutting patterns, or general requests. Triage these the same way.

Step 3: Present triage and recommend

Do NOT write the plan file until the user has reviewed the triage and chosen which threads to address. Present the triage, make a recommendation, and wait.

Present the triage to the user. Show these three sections:

Triage table

Group all threads by classification. Use a table with columns: Thread ID, File, Issue, Severity (if indicated by the reviewer — Critical, Major, Minor). Separate sections for:

• Suggestions to apply (zero-effort)
• Fixes needed (grouped by severity)
• Skipped (disagree/stale/style — with brief reason for each)
• Needs clarification

Recommendation

Suggest which threads to address together. The recommendation logic:

• Always recommend: all Critical/Major severity threads + all apply_suggestion threads (zero-effort)
• Bundle in: Minor threads that touch the same files as Critical/Major threads (marginal cost is low since you're already editing those files)
• Leave as opt-in: pure doc fixes, style nits, and threads in files with no critical issues

Ask the user

Present the decision like this:

"Recommended: N threads to fix + M suggestions to apply. K minor threads touch the same files and can be done alongside. L threads skipped (disagree/stale).

1. Fix recommended + bundled (N+M+K threads)
2. Fix all actionable threads (N+M+K+L)
3. Pick specific thread IDs
4. Just the critical/major ones (N threads)

Which option?"

Wait for the user's response. Do not proceed to Step 4 until the user has chosen.

Step 4: Write the plan artifact

Based on the user's selection, write the plan file.

Ensure .pr-review/ directory exists inside the repo. If .pr-review/ is not already in .gitignore, add it.

Write the plan file at .pr-review/pr-<N>-plan.md where <N> is the PR number.

Write incrementally — do not compose the entire document in memory first. Start by writing the header and the first file group's threads. Then append each subsequent file group. This avoids long deliberation pauses on large PRs.

What goes in the plan

• Selected threads (user chose to fix): full triage entry with fix description and draft reply
• Skipped/disagree threads: triage entry with **Fix**: None and a draft reply explaining why (these still get replied to on GitHub via /pr-review:pr-review-post)
• Deselected threads (user chose not to fix): omitted from the plan entirely — they won't be replied to or resolved

Draft replies

Write a 1-3 line draft reply for every thread in the plan (both selected and skipped). This reply will be posted to GitHub by /pr-review:pr-review-post later. Keep it concise — the fix will be in the code, not in the reply.

For actionable threads: "Fixed — [brief description of what changed]." For skipped threads: "Disagree — [brief reason]." or "Already addressed in current code." For needs_clarification: "Could you clarify — [specific question]?"

Plan file format

# PR #<N> Review Plan

**Status**: triaged
**Fetched**: <ISO timestamp>
**Review JSON**: <path to JSON file>
**Repo**: <owner/repo>

---

## Thread <thread_id> — <file>:<line> — <classification>
**Reviewer**: <username>
**Comment**: "<reviewer's comment, abbreviated if long>"
**Assessment**: <your triage reasoning>
**Fix**: <concrete fix description, or "None">
**Status**: [ ] pending
**Draft reply**: "<your 1-3 line reply>"

---

(repeat for each thread in the plan)

---

## General

(review summaries and conversation comments, same format without file/line)

---

## Summary
- X threads in plan across Y files
- N to apply (suggestions)
- N to fix
- N reply-only (skipped/disagree)
- N deselected by user (not in plan)

Step 5: Present to user

Show the user:

1. A brief summary of the plan (counts by category)
2. The path to the plan file: "Full plan at .pr-review/pr-<N>-plan.md — open in your editor to review or adjust draft replies."
3. Ask:

"Ready to apply fixes now, or do you want to review/edit the plan first?

1. Apply fixes now
2. I'll review the plan first (run /pr-review:pr-review-apply when ready)
3. Start a fresh session first (recommended for large PRs — /clear then /pr-review:pr-review-apply)

Which option?"

Wait for the user's response.

• Option 1: Announce: "Applying fixes from the plan." Then use pr-review:pr-review-apply to continue.
• Option 2 or 3: Stop here. Do not modify source files, post to GitHub, or touch CLAUDE.md.

Important guidelines

• Never blindly accept reviewer feedback. Automated reviewers can be wrong. Read the actual code before classifying anything as apply_suggestion or fix.
• Be specific. For fix items, describe exactly what should change and where, so /pr-review:pr-review-apply can act without re-reading the review.
• Group related threads. If multiple threads in the same file target the same issue, note that so they can be addressed together.
• Stale ≠ irrelevant. Even if position_stale is true, check whether the same issue exists at the current lines.
• Flag behavior changes. If a suggestion changes logic (not just style), call it out even if classified as apply_suggestion.
• This skill is read-only. The only file it creates is the plan artifact. It never modifies source files, posts to GitHub, or commits.