GitHub PR Review Skill

SKILL.md

name	pr-review-ship
description	End-to-end PR workflow: parallel code review (Opus + Codex), fix findings, push PR, monitor CI/CCR/CodeQL, address feedback, resolve threads. Use when the user says things like 'do the review and PR thing', 'run the usual workflow', 'review and ship it', 'push the PR', or 'do the usual stuff'.
allowed-tools	Bash(gh:*), Bash(git:*), Bash(python3:*), Bash(echo:*), Bash(printf:*), Bash(curl:*), task, read_agent, ask_user, skill(github-pr-reviews)

PR Review & Ship Workflow

End-to-end workflow for reviewing, pushing, and shipping a PR. This is the standard process used in this repo.

Prerequisites

• You are on a feature branch (not main)
• Changes are committed (or ready to commit)
• The branch has not been pushed yet (or needs updating)

Workflow Steps

Step 1: Parallel Code Review

Launch two code-review agents simultaneously:

• Opus (claude-opus-4.6) — deep analysis
• GPT-5.4 (gpt-5.4) — second opinion

Both review the diff of the current branch vs main. This includes all committed changes on the branch. If there are uncommitted changes, note them but review what's committed.

git diff main..HEAD

If there are uncommitted changes (git status), mention this to the user before proceeding.

Use agent_type: "code-review" with mode: "background" for both, then read_agent to collect results.

Review prompt for both agents:

Review the code changes on the current branch compared to main. Focus on bugs, logic errors, security issues, race conditions, edge cases, and type safety. Do NOT comment on style, formatting, or trivial matters.

Step 2: Fix Review Findings

• Triage findings from both reviewers
• Fix actionable issues
• Commit fixes with a descriptive message
• If fixes are significant, optionally re-run a single code-review agent to verify

Step 3: Push & Create PR

Always ask the user before pushing unless pushing was explicitly part of the current instruction.

git push -u origin <branch-name>
gh pr create --title "..." --body "..." --base main

PR body structure:

## Summary
<1-2 sentence description>

### What it does
- <bullet points of key changes>

### Key changes
- `path/to/file.ts`: <what changed>

### Security
<if applicable — note security-relevant changes>

Fixes #N

• Use Fixes #N to auto-close linked issues
• Use hyperlink URLs for GitHub items: [#N](https://github.com/owner/repo/issues/N)

Step 4: Monitor CI, CCR, and CodeQL

Delegate monitoring to a background Haiku agent — do NOT block with sleep loops.

The Haiku agent should poll every 30 seconds for:

1. CI status: gh run list --branch <branch> --limit 3 --json status,conclusion,name
2. Copilot Code Review (CCR): gh api repos/{owner}/{repo}/pulls/{N}/reviews --jq '.[] | "\(.user.login): \(.state)"'
3. CodeQL / Code Scanning: gh api repos/{owner}/{repo}/code-scanning/alerts?ref=refs/heads/<branch> --jq '.[] | "\(.number) \(.state) \(.rule.id) \(.most_recent_instance.location.path):\(.most_recent_instance.location.start_line)"'

Also check for inline review comments:

gh api repos/{owner}/{repo}/pulls/{N}/comments --jq '.[] | "[\(.user.login)] \(.path):\(.line) - \(.body[0:500])"'

The agent should keep polling until CI completes AND at least one review appears (CCR can take 2-5 minutes).

Report all results verbatim.

Step 5: Address CCR/CodeQL Feedback

For each comment, decide:

• Fix: Address the issue, commit with a descriptive message
• Defer: Note the reason (e.g., "low risk for v1", "follow-up issue", "admin-only code path")
• Dismiss (CodeQL only): Use REST API with a reason if it's a false positive

Commit all fixes in a single commit if possible:

fix: address CCR feedback on <feature> PR

- <bullet point per fix>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Push the fixes.

Step 6: Resolve Review Threads

Use the github-pr-reviews skill to batch-resolve all review threads.

If the skill is not available, resolve manually via GraphQL:

# Get unresolved thread IDs
gh api graphql -f query="{ repository(owner: \"$OWNER\", name: \"$REPO\") { pullRequest(number: $PR) { reviewThreads(first: 50) { nodes { id isResolved } } } } }"

# Resolve each
gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "PRRT_xxx"}) { thread { isResolved } } }'

Note: Code scanning threads (from github-advanced-security) cannot be resolved via GraphQL — they auto-close when the code is fixed.

Step 7: Report Status

Summarize for the user:

• ✅/❌ CI status
• ✅/❌ CCR — how many comments, how many fixed vs deferred
• ✅/❌ CodeQL — any alerts, status
• ✅/❌ Review threads resolved
• PR URL and ready-to-merge status

Conventions

• Git trailers: Always include Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
• Ask before push: Never push without asking unless the user explicitly said to push
• Hyperlinks: Reference GH items as [#N](url), not plain #N
• Background monitoring: Use Haiku agents for polling, not sleep loops in main context
• Deferred items need reasons: When skipping a review comment, explain why