pr-review-responder

name	pr-review-responder
description	Respond to and address PR review comments. Fetches PR context, tracks resolution progress, and supports a workflow for systematically addressing reviewer feedback with agent assistance.

PR Review Responder

Respond to PR review feedback by fetching comments, tracking resolution progress, and systematically addressing reviewer feedback.

Quick Start

Step 1: Checkout the PR branch (REQUIRED)

Before making any changes, you MUST checkout the PR branch:

gh pr checkout <pr-number>

This ensures you're working on the correct branch and changes will be pushed to the PR. For stacked diffs, use the stacked-diffs skill to sync the correct branch.

Step 2: Fetch and respond to comments

Prefer the pr-review-fetcher agent first for review data collection. It is generally more robust than the local scripts when GitHub review-thread GraphQL data is inconsistent or partially unavailable. Use fetch_pr.py / progress.py as fallback or for local double-checking.

# Fetch PR data (run from within a git repo)
python3 scripts/fetch_pr.py <pr-number> --format text

# Show only unresolved comments
python3 scripts/fetch_pr.py <pr-number> --unresolved-only --no-diff

# Mark a comment as resolved (auto-minimizes)
python3 scripts/mark_resolved.py <comment-id> [--comment "optional note"]

# Remove resolution marker
python3 scripts/mark_resolved.py <comment-id> --unmark

Resolved comments are minimized automatically; failures are reported in the CLI output. No need to run a separate minimize command.

Skill awareness: This is a CLI skill (not an agent). Use command/pr-respond to orchestrate; use the pr-review-fetcher agent as the default data source; use general agents to address code changes. For stacked diffs, use the stacked-diffs/git-town skill to switch and sync the correct branch before editing.

Scripts

fetch_pr.py

Fetches comprehensive PR data including metadata, changed files, diffs, and all comments.

python3 scripts/fetch_pr.py <pr-number-or-url> [options]

Options:

• --unresolved-only - Only show unresolved comments
• --no-diff - Exclude the full diff from output
• --format json|text - Output format (default: json)

Output includes:

• PR metadata (title, author, state, branches, URL)
• Changed files with additions/deletions counts
• Review comments (inline code comments attached to specific lines) with resolution status
• PR conversation comments (general issue comments on the PR)
• Full diff (unless --no-diff)

Important: The script fetches BOTH types of comments:

1. Review comments - Inline comments attached to specific lines of code via repos/{owner}/{repo}/pulls/{pr}/comments
2. Issue comments - General conversation comments on the PR via repos/{owner}/{repo}/issues/{pr}/comments

Both may contain actionable review feedback.

Resolution detection: The script detects resolved comments via two methods:

1. GitHub's native thread resolution - Uses GraphQL to fetch isResolved state from review threads
2. Resolution marker - Checks for <[resolved]> in comment body (fallback/manual marking)

A comment is considered resolved if EITHER condition is true. This ensures all resolved comments are correctly identified, including those resolved via GitHub's UI.

mark_resolved.py

Marks review comments as resolved by appending a marker to the comment body.

python3 scripts/mark_resolved.py <comment-id> [options]

Options:

• --unmark - Remove the resolution marker instead of adding it
• --dry-run - Preview changes without modifying

Resolution Marker

GitHub's inline review comments cannot be programmatically resolved via API. This skill uses a text marker appended to comment bodies:

<[resolved]>

> Marked as resolved by OpenCode Code Review Skill

Why this format:

• <[resolved]> uses angle brackets that render as text (not HTML)
• Square brackets make it visually distinct and easy to grep
• Unlikely to appear naturally in comments

Detecting resolution status:

• Resolved: comment body contains <[resolved]>
• Unresolved: comment body does NOT contain <[resolved]>

Direct CLI Commands

For quick access without scripts:

# Get changed files
gh pr diff <pr-number> --name-only

# Get full diff
gh pr diff <pr-number>

# Get PR metadata as JSON
gh pr view <pr-number> --json title,author,state,files,comments,reviews

# Get inline review comments via API
gh api repos/{owner}/{repo}/pulls/<pr-number>/comments

progress.py

Check progress on resolving PR review comments.

python3 scripts/progress.py <pr-number> [options]

Options:

• --verbose, -v - Show details of unresolved comments
• --json - Output as JSON
• --no-issue-comments - Exclude general PR conversation comments (only track inline code review comments)

Output:

PR #22: Feature XYZ
URL: https://github.com/owner/repo/pull/22

Progress: [████████░░░░░░░░░░░░░░░░░░░░░░] 27%
Status: 11/15 remaining (4 resolved)
  (10 inline review, 5 conversation)

Note: By default, progress.py tracks BOTH inline code review comments AND general PR conversation comments, since both may contain actionable review feedback. Use --no-issue-comments to exclude conversation comments if needed.

Integrated Workflow

Use this workflow to systematically address PR review comments with agent assistance.

Step 1: Checkout PR Branch (REQUIRED)

You MUST checkout the PR branch before making any changes:

gh pr checkout <pr-number>

This is critical because:

• Ensures you're editing files on the correct branch
• Changes will be pushed to the PR when you git push
• The diff context matches what reviewers see

For stacked diffs, use the stacked-diffs skill to sync the correct branch.

Step 2: Fetch and Triage

# Preferred: fetch review data with the pr-review-fetcher agent
# Ask it for unresolved inline comments, actionable conversation comments,
# and a concise triage list.

# Optional fallback / local cross-check: get overview of all comments
python3 scripts/progress.py <pr-number> --verbose

# Optional fallback / local cross-check: get full context with diffs
python3 scripts/fetch_pr.py <pr-number> --format json > pr_data.json

Recommended fetch order:

1. pr-review-fetcher agent for the current unresolved review state.
2. fetch_pr.py --unresolved-only --no-diff if you want a local JSON snapshot.
3. progress.py --verbose as a quick progress cross-check.

If the local scripts fail to fetch review threads or return incomplete data, continue with the agent-derived review state instead of blocking on the scripts.

Review each comment and categorize:

• Address - Valid feedback requiring code changes
• Dismiss - Not applicable/false positive; mark resolved (optional note only if user supplies it); auto-minimizes
• Skip - Leave unresolved for later; take no action now

Step 2: Dismiss or Skip Non-Actionable Comments

For comments you don't plan to address now:

# Dismiss: mark as resolved (only add --comment if the user already provided text)
python3 scripts/mark_resolved.py <comment-id> [--comment "optional note"]

Resolved comments are minimized automatically; failures are reported in CLI output. Do not prompt the user for a comment; only include one if provided. Skipped comments remain untouched and unresolved.

Step 3: Address Valid Feedback

For each comment requiring changes, dispatch an agent with context:

Address this PR review comment:

File: {path}
Line: {line}
Comment: {body}
Diff context:
{diff_hunk}

Make the necessary code changes to address this feedback.

Step 4: Mark Resolved After Changes

After implementing changes for a comment:

python3 scripts/mark_resolved.py <comment-id>

Step 5: Check Progress

python3 scripts/progress.py <pr-number>

Repeat steps 3-5 until all comments are resolved.

Workflow Example

# 1. Initial assessment
# Preferred: ask pr-review-fetcher for unresolved actionable feedback
# Optional local cross-check:
python3 scripts/progress.py 22 --verbose
# Output: 5/5 remaining

# 2. Dismiss a false positive
python3 scripts/mark_resolved.py 2639114002

# 3. Check progress
python3 scripts/progress.py 22
# Output: 4/5 remaining

# 4. Get context for next comment to address
python3 scripts/fetch_pr.py 22 --unresolved-only --no-diff --format json

# 5. After making code changes, mark resolved
python3 scripts/mark_resolved.py 2639114004

# 6. Repeat until done
python3 scripts/progress.py 22
# Output: 0/5 remaining - all resolved!

Agent Integration

When dispatching agents to address comments, provide:

1. Comment details - ID, path, line, body
2. Diff context - The diff_hunk field shows surrounding code
3. Full file if needed - Read the file for broader context
4. Clear instruction - What change to make

Example agent prompt:

Address PR review comment #2639114004:

The reviewer says: "The example POST payload is missing required fields"

File: docs/api.md, Line: 113
Context:
```json
{
  "name": "example"
}

Update the example to include all required fields per the API spec. After making changes, I will mark comment 2639114004 as resolved.

## Resources

- `scripts/fetch_pr.py` - Fetch PR data
- `scripts/mark_resolved.py` - Mark/unmark comments as resolved  
- `scripts/progress.py` - Check resolution progress
- `references/api_reference.md` - GitHub API field reference