GitHub PR Workflows Skill

GitHub PR Workflows

Load if: Creating PRs, reviewing code, merging, stacked PRs
Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md, @smith-git/SKILL.md

</metadata>

CRITICAL (Primacy Zone)

MUST run quality checks before creating PR
MUST ensure branch is up-to-date before requesting review or merging
MUST link to related issues
MUST have all CI checks passing before merge
MUST have explicit user request before creating PRs -- listing is NOT consent to create

</required>

Avoid GitHub MCP

GitHub MCP tools (mcp__github__*) - hard to control pagination (token waste), less complete than CLI, requires personal token

</forbidden>

Use instead: gh pr-review extension, gh api, or GraphQL queries

PR Title Format

Follow conventional commits format. See @smith-style/SKILL.md for details.

PR Creation Workflow

Pre-PR checklist:

Run linter and formatter
Run tests
Rebase onto parent branch (not always main - check stacked PRs)
Push to remote

</required>

AI-generated descriptions: Analyze full diff, read ALL commits, identify tickets, generate structured summary (What/Why/Testing/Dependencies).

Working on Existing PRs

ALWAYS get actual branch name: gh pr view {PR} --json headRefName
ALWAYS check for review comments before making changes
ALWAYS update PR title/body after pushing changes

</required>

Code Review Cycle

Fetch review comments using gh pr-review (see "Fetching Review Comments" below)
Get ALL comments including Nitpicks - don't skip minor issues
Categorize: Actionable > Nitpick > Clarification > Discussion
Proactively audit similar issues in other files not explicitly mentioned
Implement fixes with confidence scoring (high: implement, low: ask)
- High confidence: Small surface area change, aligns with existing patterns, covered by tests
- Low confidence: Ambiguous behavior, architectural impact, requires design discussion
Reply to comments with commit SHA
Resolve threads after addressing - don't leave resolved issues open
Re-check for new comments after CI passes

Code review response rules:

File-inline comments (on specific lines): MUST reply in-thread using gh pr-review comments reply --thread-id {PRRT_xxx}, NOT as PR-level comment. This keeps discussion traceable to the code location.
PR-level comments (general discussion, <details> blocks): Reply with gh pr comment or GitHub's "Quote reply"
Reply with commit SHA, then resolve thread with gh pr-review threads resolve
Proactive audit: search codebase for similar issues before committing
CodeRabbit <details> comments (Nitpicks, Duplicated, Outside diff range): These appear in PR thread, not inline on files. Use GitHub's "Quote reply" to include Markdown blockquote of the essential part (e.g., > The redundant text...), making response traceable
Attribution: When Claude Code generates or posts a comment, state authorship with the user's @ mention per medium (e.g., GitHub: "Posted by Claude Code on behalf of @username", Notion: "Posted by Claude Code on behalf of @Display Name"). Omit when the user manually authors the comment.
Research questionable suggestions before implementing (see @smith-research/SKILL.md)

Review reply tone and style:

Concise: Lead with the action taken or answer; no filler
Evidence-based: Cite commit SHA, file:line, docs URL, or test output as proof — strongest evidence available
Grateful: Thank the reviewer for catching the issue (e.g., "Good catch — fixed in abc1234")
Humble: If uncertain, say so; don't over-explain or defend — ask for guidance instead
Gentle: When disagreeing, present evidence respectfully (e.g., "I kept X because [reason] — happy to change if you see it differently")

</required> <forbidden>

NEVER reply to file-inline comments with gh pr comment (loses thread context)
NEVER mention @copilot in replies (triggers unwanted sub-PRs)

</forbidden>

Review Convergence Protocol

Decide-and-proceed defaults (do NOT ask between obvious steps):

CR finding is Critical/Warning + high-confidence: fix, commit, push silently
CR finding is Info/Nitpick: reply-and-resolve or skip with one-line reason
After pushing a fix: re-run review immediately
0 actionable findings: merge (gh pr merge --squash --delete-branch)
Post-merge: ExitWorktree action="remove" → git pull --ff-only (see @smith-worktree/SKILL.md Sync-After-Squash-Merge)

Must-ask criteria (only interruption triggers):

Finding requires scope change beyond the PR's stated goal
Finding contradicts an existing smith-skill rule (meta-question)
Auto-mode classifier denial without a documented escape pattern
CI fails after a CR-driven fix (regression vs flake ambiguity)
User explicitly said "pause" or "wait" in recent turns

Convergence criteria:

Clean round (0 Critical/Warning findings): ready to merge
Diminishing returns (2 consecutive rounds with only Info/Nitpick): merge
Flip-flop (reviewer alternates contradicting verdicts without new evidence): escalate trade-off analysis to user, stop iterating

External write rule (Notion, Slack, Jira, GitHub comments):

Draft content inline in conversation first
State intent: "posting to [medium]" — user can interrupt
Post unless user objects within that turn
Always include attribution line per medium convention

</required>

Fetching Review Comments

Use gh pr-review over gh api - structured output with thread IDs.

All commands require --pr {number} -R {owner}/{repo} for numeric PR selectors.

</required>

Install: gh extension install agynio/gh-pr-review (consider pinning to vetted SHA)

On gh pr-review errors:

Check if extension installed: gh extension list | grep pr-review
Verify command syntax (common: missing --pr, wrong -R format)
Verify repo name: gh repo view --json nameWithOwner
If not installed: gh extension install agynio/gh-pr-review

List unresolved threads: gh pr-review threads list --pr {number} -R {owner}/{repo} --unresolved

gh-pr-review Commands

View reviews (use --unresolved, --reviewer, --states to filter): gh pr-review review view --pr {number} -R {owner}/{repo}

Reply to thread: gh pr-review comments reply --pr {number} -R {owner}/{repo} --thread-id {PRRT_xxx} --body "..."

Resolve/unresolve thread: gh pr-review threads resolve --pr {number} -R {owner}/{repo} --thread-id {PRRT_xxx}

Output includes thread_id (PRRT_xxx format) needed for reply/resolve operations.

REST API (Single Comments)

URL patterns map to API endpoints:

#issuecomment-{id} → gh api repos/{owner}/{repo}/issues/comments/{id}
#discussion_r{id} → gh api repos/{owner}/{repo}/pulls/comments/{id}
#pullrequestreview-{id} → gh api repos/{owner}/{repo}/pulls/{pr}/reviews/{id}

Rebase Decision Tree

Behind base, no conflicts, explicit "update": AUTO-REBASE Behind base, no conflicts, not explicit: ASK user Behind base, conflicts detected: INFORM + ASK Parent PR merged: INFORM + OFFER cascade About to request review, outdated: BLOCK + INFORM

Staleness thresholds: <5 commits (fresh), 5-10 (notify), >10 (recommend), >20 (urgent)

Note: The above decision tree provides guidance during active development. The MUST requirement for up-to-date branches is enforced when requesting review or merging.

Merge Strategies

Merge commit: Feature branches with meaningful history Squash: Small fixes, docs, single logical change Rebase: Linear history required, clean commits

Stacked PRs

For stacked PRs, merge parent WITHOUT --delete-branch, then:

gh pr edit {CHILD} --base main
git rebase --onto origin/main feat/parent_branch
git push --force-with-lease
git push origin --delete feat/parent_branch

/ultrareview — Cloud Deep-Review

/ultrareview (research preview, v2.1.86+) runs a multi-agent reviewer fleet in a remote Claude Code on the web sandbox. Higher signal than the built-in single-pass /review slash command: every finding is independently reproduced and verified before it's reported. Takes 5–10 min; runs in background so the terminal stays free.

Invocation:

/ultrareview — review diff between current branch and default branch (includes uncommitted/staged)
/ultrareview <PR> — review a GitHub PR (PR mode; clones from GitHub directly, requires github.com remote)
claude ultrareview [<PR>|<base>] — non-interactive variant; prints findings to stdout; flags --json, --timeout <minutes>

Requires: authenticated with claude.ai (run /login), not available on Bedrock/Vertex/Foundry or for Zero Data Retention organizations.

Billing: Pro/Max get 3 one-time free runs; after that, billed as usage credits (~$5–$20/run by change size). Team/Enterprise has no free runs. Account must have usage credits enabled (/usage-credits to check). User-invoked only — agent does not start one on its own.

Track: /tasks shows running reviews. Stopping a review archives the cloud session and doesn't return partial findings; a stopped/failed run still consumes a free run.

When to recommend over the built-in /review: before merging a substantial change where pre-merge confidence matters; not for quick iterative feedback. Source: https://code.claude.com/docs/en/ultrareview

</context>

Automated PR Review Monitoring

/loop for review cycles — periodically poll for new review comments and auto-address them:

/loop 5m /smith-gh-pr:check-reviews

Note: check-reviews is a conceptual pattern, not a built-in sub-command. Implement the workflow below manually or as a custom skill. For /loop semantics see @smith-automation/SKILL.md.

Auto-address workflow (see "Review Convergence Protocol" above for decide-vs-ask criteria and convergence rules):

Fetch unresolved comments: gh pr-review threads list --pr {number} -R {owner}/{repo} --unresolved
Classify each: code change vs clarification vs resolved
High-confidence fixes: implement, commit, reply with SHA
Low-confidence: draft reply, ask user before posting
Re-check after CI passes

Proactive self-review — before reviewer sees changes:

Run CodeRabbit review via configured integration (e.g. coderabbit:review skill or GitHub App) after pushing
Address mechanical feedback (lint, naming, tests) before human review begins

/autofix-pr — cloud auto-fix loop

Run /autofix-pr while on the PR's branch. Claude Code detects the open PR with gh, spawns a Claude Code on the web session, and turns on auto-fix for that PR in one step. The web session subscribes to GitHub events (CI checks, review comments) and pushes fixes for high-confidence cases; ambiguous changes prompt instead of pushing.

Requires the Claude GitHub App installed on the repo (PR webhooks). Replies to review threads post under the user's GitHub account but are labeled as Claude Code authored. Disable per-PR via the web session's CI status bar.

Warning: if the repo uses comment-triggered automation (Atlantis, Terraform Cloud, GitHub Actions on issue_comment), auto-fix's review replies can trigger those workflows. Avoid auto-fix where a PR comment can deploy infrastructure or run privileged operations.

Source: https://code.claude.com/docs/en/claude-code-on-the-web#auto-fix-pull-requests

When to use the monitoring loop pattern (above) vs /autofix-pr:

Loop pattern: terminal stays attached; agent under the user's direct supervision; user controls each push
/autofix-pr: terminal can close; runs autonomously in cloud; for PRs where you're confident in unattended fixing

</context>

Claude Code Plugin Integration

When plugins are available, prefer plugin commands:

/code-review: Launches 4 parallel agents with confidence scoring (threshold 80)
/commit-push-pr: Commits, pushes, and creates PR in one step
pr-review-toolkit agents: Specialized review via Task tool
- code-reviewer - CLAUDE.md compliance, style, bugs
- silent-failure-hunter - Error handling issues
- pr-test-analyzer - Test coverage gaps

Plugin commands complement (not replace) manual gh workflows.

</context> <related>

@smith-gh-cli/SKILL.md - GitHub CLI commands, pagination limits
@smith-stacks/SKILL.md - Stacked PR workflows
@smith-git/SKILL.md - Git operations, rebase
@smith-style/SKILL.md - Conventional commits, branch naming
@smith-tests/SKILL.md - Testing standards (pre-PR checklist)
@smith-research/SKILL.md - Research best practices before implementing review feedback
@smith-validation/SKILL.md - Debugging, root cause analysis for review issues

</related>

ACTION (Recency Zone)

Create PR:

gh pr create --title "feat: add feature" --body "..." --assignee @me

Merge PR:

gh pr merge {PR} --squash

Options: --squash, --merge, or --rebase

Post-merge cleanup:

git checkout main && git fetch --prune origin && git pull
git branch -d feat/my_feature

Check freshness:

git fetch origin
BEHIND=$(git rev-list HEAD..origin/main --count)

Agent Skills: GitHub PR Workflows

Install this agent skill to your local

Skill Files