Instrucciones de origen · Vista previa de solo lectura
name
pr-review-import
description
Import PR review comments into a review report for team-branch-fix
argument-hint
<PR URL or number> [filter instructions]
PR Review Import
Import review comments from a GitHub PR and convert them into the standard review report format consumed by /team-branch-fix and /team-branch-comment.
Context
Working directory: !pwd
Current branch: !git branch --show-current
Instructions
You are importing PR review comments and converting them into the standard branch review report format. This is a single-agent skill - no team or subagents needed.
This skill does NOT edit files. It produces a review report only.
Phase 0: Prerequisites Guard
Step 1: gh authentication
gh auth status
If not authenticated, stop and tell the user: "GitHub CLI is not authenticated. Run gh auth login first."
If this fails, stop and tell the user: "Current directory is not a GitHub repository (or gh cannot detect one)."
Record OWNER and REPO from the output.
Phase 1: Parse Input
The user's input comes from $ARGUMENTS. Parse it to extract:
PR identifier: Either a full URL (https://github.com/org/repo/pull/123) or a bare number (123)
From a URL: extract owner, repo, and PR number. These override the OWNER/REPO from Phase 0.
From a bare number: use OWNER/REPO from Phase 0.
Filter instructions: Any text after the PR identifier. This is free-text that Claude interprets naturally (e.g., "only from @user", "ignore bot comments", "only security-related").
Record PR_NUMBER and any FILTER_TEXT.
Phase 2: Branch Guard
Compare local HEAD against the PR's head SHA to ensure we're on the right branch.
Step 1: Fetch PR head ref and SHA
gh api repos/OWNER/REPO/pulls/PR_NUMBER --jq '{head_sha: .head.sha, head_ref: .head.ref}'
Record PR_HEAD_SHA and PR_HEAD_REF.
Step 2: Get local HEAD and check for uncommitted changes
git rev-parse HEAD
git status --porcelain
Record LOCAL_HEAD and whether there are UNCOMMITTED_CHANGES (non-empty output from git status).
Step 3: Compare
If PR_HEAD_SHA != LOCAL_HEAD:
Warn the user: "Branch mismatch: PR head is PR_HEAD_SHA (branch PR_HEAD_REF) but local HEAD is LOCAL_HEAD."
If UNCOMMITTED_CHANGES is non-empty, also warn: "Note: you have uncommitted changes on the current branch that would need to be stashed or committed before switching."
Ask to confirm via AskUserQuestion. Build the options list dynamically:
If no uncommitted changes:
Call AskUserQuestion tool with:
questions: [{
question: "PR head SHA does not match local HEAD. The PR branch is `PR_HEAD_REF`. What would you like to do?",
header: "Branch mismatch",
options: [
{ label: "Switch branch", description: "Run `git checkout PR_HEAD_REF` to switch to the PR branch" },
{ label: "Continue", description: "Proceed despite SHA mismatch - report will still reference PR comments" },
{ label: "Abort", description: "Stop and let me sort this out manually" }
],
multiSelect: false
}]
If uncommitted changes exist:
Call AskUserQuestion tool with:
questions: [{
question: "PR head SHA does not match local HEAD. The PR branch is `PR_HEAD_REF`. You have uncommitted changes on the current branch. What would you like to do?",
header: "Branch mismatch",
options: [
{ label: "Stash and switch", description: "Run `git stash` then `git checkout PR_HEAD_REF`" },
{ label: "Continue", description: "Proceed despite SHA mismatch - report will still reference PR comments" },
{ label: "Abort", description: "Stop and let me sort this out manually" }
],
multiSelect: false
}]
Handling the response:
Switch branch: Run git checkout PR_HEAD_REF. If it fails, stop with the error.
Stash and switch: Run git stash then git checkout PR_HEAD_REF. If either fails, stop with the error. Note to the user that their changes are stashed.
Continue: Proceed with the import despite the mismatch.
Abort: Stop immediately.
Phase 3: Fetch Comments
Fetch all three comment types with pagination:
# Review comments (inline code comments)
gh api --paginate repos/OWNER/REPO/pulls/PR_NUMBER/comments
# Reviews (top-level review bodies)
gh api --paginate repos/OWNER/REPO/pulls/PR_NUMBER/reviews
# Issue comments (general PR discussion)
gh api --paginate repos/OWNER/REPO/issues/PR_NUMBER/comments
Parse the JSON responses and record the total count across all three sources.
Phase 4: Soft Cap
If total comments across all three sources > 100:
Call AskUserQuestion tool with:
questions: [{
question: "This PR has N total comments. Processing all of them may take a while. Continue?",
header: "Many comments",
options: [
{ label: "Continue", description: "Process all N comments" },
{ label: "Abort", description: "Stop - I'll re-run with a filter" }
],
multiSelect: false
}]
If the user selects "Abort", stop immediately.
Phase 5: Apply Filters
If FILTER_TEXT is non-empty, apply the user's filter instructions to the collected comments. Claude interprets these naturally:
"only from @user" - keep only comments authored by that user
"ignore bot comments" - remove comments from bot accounts
"only security-related" - keep only comments discussing security topics
Any other free-text filter
Default behavior (no filter): Include ALL comments, including bot comments.
Phase 6: Collapse Threads
Group review comments into threads:
For each review comment with in_reply_to_id, walk the chain to find the root comment
Group all replies under their root comment
Merge reply text in created_at order into the parent finding's description, preserving each reply as a quoted block with author attribution
Use the root comment's path and line/original_line for the finding's file location
Use the root comment's id as the Comment ID
Collect ALL unique authors across the thread into the "Found by" field: @user1, @user2
Phase 7: Drop Non-Actionable
Remove comments that are not actionable:
Empty bodies (null or whitespace-only)
Pure approval signals: "LGTM", "Looks good", "Looks good to me", thumbs-up-only
Pure emoji reactions with no text content
Keep everything else - even short comments may contain actionable feedback.
Phase 8: Classify Findings
For each remaining comment, classify:
Severity: Critical / High / Medium / Low
Critical: Security vulnerabilities, data loss, crashes
Category: Security, Performance, Logic, Style, Documentation, Error Handling, Testing, Architecture, Correctness, or other appropriate category
Use the comment content and context to determine appropriate classification. When a thread has discussion that refines or resolves the issue, factor that into the severity.
Phase 9: Optional Codex Validation
Call AskUserQuestion tool with:
questions: [{
question: "Run Codex validation on imported findings? (validates each finding against the codebase)",
header: "Codex validation",
options: [
{ label: "Yes", description: "Validate each finding with Codex MCP - adds confidence scores" },
{ label: "No", description: "Skip validation - faster, findings reported as-is" }
],
multiSelect: false
}]
If yes: For each finding, call mcp__codex__codex asking it to validate whether the finding is legitimate given the current codebase. Add a Validation field to each finding with the result (Confirmed/Disputed and rationale).
If no: Omit the Validation field from findings entirely.
Phase 10: Generate Report
Format the report to match the team-branch-review output structure. Use the template from ~/.claude/skills/team-branch-review/templates/final-report.md as the canonical format.
Key differences from a standard team-branch-review report:
The "Review Team" line says Imported from PR #N instead of reviewer count
Multi-line review comment (start_line differs from line)
path:start_line-line
Review body (top-level review text)
(general)
Issue comment (PR discussion)
(general)
Report structure:
# Branch Review: BRANCH_NAME
## Overview
- **Branch**: BRANCH_NAME -> main-**Commits**: N commits
-**Files Changed**: N files (+X/-Y lines)
-**Review Team**: Imported from PR #PR_NUMBER
- **Reviewers**: [list of unique comment authors]
## Outcome: [APPROVED | NEEDS REVISION | MANUAL REVIEW REQUIRED]
Determination:
- APPROVED: No Critical or High findings
- NEEDS REVISION: Any Critical or High findings remain
- MANUAL REVIEW REQUIRED: Findings are ambiguous or contested in thread discussion
---
## Critical & High Findings
### [Finding Title]
- **File**: path:line
- **Severity**: Critical/High
- **Category**: [concern area]
- **Issue**: Description (from comment body, with thread context merged)
- **Suggestion**: Concrete fix (if suggested in the comment)
- **Validation**: [Only if Codex validation was run] [Confirmed/Disputed] by Codex ([confidence]) - [rationale]
- **Found by**: @author1, @author2
- **Comment ID**: 1234567890
- **Comment Type**: review_comment
-**Source URL**: https://github.com/...
[Repeat for each]
---
## Medium & Low Findings
[Same format, grouped by category]
---
## Review Statistics- Total comments fetched: N
- After filtering: N
- After thread collapsing: N
- After dropping non-actionable: N
- Final findings: N
- By severity: Critical: N, High: N, Medium: N, Low: N
- By type: review_comment: N, issue_comment: N, review_body: N
Outcome determination:
APPROVED: No Critical or High severity findings
NEEDS REVISION: Any Critical or High severity findings exist
MANUAL REVIEW REQUIRED: Findings have significant back-and-forth in threads suggesting disagreement
Phase 11: Output
Display the full report in the conversation
Write the report to /tmp/pr-review-import-OWNER-REPO-PR_NUMBER.md
Report the temp file path to the user
After presenting the report, add this note:
Next steps:
/team-branch-fix - Implement fixes for these findings
/team-branch-comment - Post findings back as PR review comments (useful for cross-posting or re-posting refined comments)
Error Handling
Scenario
Recovery
gh not authenticated
Stop with message to run gh auth login
Not in a GitHub repo
Stop with message
PR not found (404)
Stop with message: "PR #N not found in OWNER/REPO"
No comments on PR
Report "No review comments found on PR #N" and exit
All comments filtered out
Report "All N comments were filtered out. Try a broader filter."
Branch mismatch
Warn and ask for override
Codex MCP unavailable
Skip validation, note in report
API rate limiting
Wait and retry with backoff
Guidelines
Single agent: No team or subagents needed
Read-only: This skill does NOT edit any files - it only reads PR data and produces a report
Thread awareness: Collapsed threads are the primary unit of work, not individual comments
Preserve original text: Include the actual comment text in findings, don't paraphrase
Faithful classification: Classify based on comment content, not assumptions
Compatible output: The report MUST be parseable by /team-branch-fix and /team-branch-comment
