PR Review Workflow

Systematic workflow for checking, responding to, and reporting on PR feedback from any source — human reviewers, review bots (CodeRabbit, Gemini, Codex, Snyk, etc.), or AI agents.

Requirements: GitHub repository with GitHub CLI (gh ) installed and authenticated.

Key insight: PR feedback arrives through three different channels (conversation comments, inline threads, review submissions). Missing any channel means missing feedback. This skill ensures all channels are checked systematically.

Self-Contained Constraint

ALL operations MUST go through the provided scripts. Never run raw git , gh , date , or bash heredocs (cat > file << 'EOF' ) when a script or agent tool covers the same operation.

Instead of (prohibited) Use

git status , git branch , gh pr view , gh repo view

get-context.sh

git add , git commit , git push

commit-and-push.sh

git checkout -b , git switch -c

open-branch.sh

gh pr create

create-pr.sh

gh api repos/.../comments , gh pr view --json

check-pr-feedback.sh

gh api ... -f body= (posting comments) post-fix-report.sh or reply-to-inline.sh

date -u +%Y-%m-%dT%H:%M:%SZ

get-context.sh (outputs timestamp: field)

cat > file.md << 'EOF' (bash heredoc) Agent's native Write tool to .agents/scratch/ , then pass file path to script

echo "..." | script.sh (piped stdin) Script's direct flag: -m , --body , or file-path argument

Entry point: Always start with get-context.sh to detect current state. Use its output to decide next steps via the Decision Tree below.

File creation: When a script accepts a file path (e.g., create-pr.sh --body , post-fix-report.sh ), write the file to .agents/scratch/ using the agent's native Write tool, then pass the path to the script. Never use bash heredocs to create temp files.

• Directory: .agents/scratch/ — inside the repo, avoids out-of-tree write permission prompts

• Setup: Run mkdir -p .agents/scratch before the first write if it doesn't exist

• Gitignore: Ensure .agents/ is in the project's .gitignore

• Cleanup: Scripts auto-delete scratch files after reading them, so the file won't exist on subsequent runs (no overwrite prompts)

Acceptable raw commands: Project-specific test/build commands (npm test , npm run <script> , pytest , make build , etc.) are fine — these are not PR workflow operations. For creating test fixtures, use the agent's native Write tool (write to .agents/scratch/ ) instead of printf or echo redirects. Avoid echo ... | command — piped commands trigger permission prompts in sandboxed environments.

Entry Point Decision Tree

Run get-context.sh first. Based on its output, follow the matching path:

on_default

has_changes

pr_number

Action sequence

true

true

empty open-branch.sh → commit-and-push.sh → create-pr.sh --invoke --title "..."

true

false

empty Ask user what to do (no changes to work with)

false

any has number check-pr-feedback.sh (existing PR — review cycle)

false

true

empty commit-and-push.sh → create-pr.sh --invoke --title "..."

false

false

empty create-pr.sh --invoke --title "..." (branch exists, already pushed)

For loop mode, see the Loop Mode section — the decision tree gets you started, then the loop takes over.

Quick Commands

Script path resolution: Before running any script, determine the correct base path. Check in this order:

• ~/.claude/skills/pr-review/scripts/ — global install for Claude Code

• Other global paths by preference of the agent

Use whichever path exists. Script paths below use the global form; substitute accordingly for your agent or install method.

Get Context (Entry Point)

~/.claude/skills/pr-review/scripts/get-context.sh

Outputs key-value pairs: branch , on_default , has_changes , change_summary , pr_number , pr_url , pr_state , timestamp , repo . Use timestamp for wait-for-reviews.sh --since . Gracefully handles missing gh (empty PR/repo fields). Exits 1 only on detached HEAD or not in a git repo.

Open Branch (Idempotent)

~/.claude/skills/pr-review/scripts/open-branch.sh [BRANCH_NAME]

If already on a non-main/master branch, prints branch name and exits. If on main/master, creates branch, switches, and pushes with -u . Default name: review-loop-YYYYMMDD-HHMMSS .

Check All Feedback (CRITICAL - Use First)

~/.claude/skills/pr-review/scripts/check-pr-feedback.sh [PR_NUMBER]

Checks all three channels: conversation comments, inline comments, reviews.

If no PR number provided, detects current PR from branch.

Reply to Inline Comment

~/.claude/skills/pr-review/scripts/reply-to-inline.sh <COMMENT_ID> "Your message" ~/.claude/skills/pr-review/scripts/reply-to-inline.sh <COMMENT_ID> .agents/scratch/reply.md

Replies in-thread to inline comments. Accepts message as inline text or a file path (auto-detects). Use file path when message contains ${...} or other shell-sensitive syntax to avoid permission prompts. Uses -F flag (not --raw-field ) which properly handles numeric ID conversion in gh CLI.

Must be run from repository root with an active PR branch.

Important: Always sign inline replies with your agent identity (e.g., —Claude Sonnet 4.5 , —GPT-4 , —Custom Agent ) to distinguish agent responses from human responses in the GitHub UI.

Invoke Review Agents

~/.claude/skills/pr-review/scripts/invoke-review-agents.sh [--agents SLUG,...] [--format-only] [PR_NUMBER]

Posts trigger comments to start agent reviews. Without --agents , invokes all known agents (Codex, Gemini, CodeRabbit). Use --list to see available agents. Use --format-only to print trigger text to stdout without posting (for embedding in PR body).

Post Fix Report

~/.claude/skills/pr-review/scripts/post-fix-report.sh [PR_NUMBER] .agents/scratch/fix-report.md

Create PR (Idempotent)

~/.claude/skills/pr-review/scripts/create-pr.sh --title "PR title" --body .agents/scratch/pr-body.md [--invoke]

Or body as inline text:

~/.claude/skills/pr-review/scripts/create-pr.sh --title "PR title" --body "Short description"

--body auto-detects: if the value is a readable file, reads from it; otherwise treats as text. Idempotent: if a PR already exists, outputs its info. Refuses to run on main /master . Pushes branch if not yet pushed.

--invoke appends review agent trigger text to the PR body (via invoke-review-agents.sh --format-only ), avoiding a separate trigger comment that causes double-invocations when auto-review is enabled.

Output prefixes (machine-parseable):

• EXISTS: <url> — PR already existed for this branch

• CREATED: <url> — new PR was created

Commit and Push

~/.claude/skills/pr-review/scripts/commit-and-push.sh -m "fix: address review feedback"

Stages all changes, commits, and pushes. Refuses to run on main /master . Never force-pushes. Outputs commit hash and branch.

Wait for Reviews

~/.claude/skills/pr-review/scripts/wait-for-reviews.sh [PR_NUMBER] --since TIMESTAMP [--timeout 600] [--interval 30]

Polls all three feedback channels for new comments posted after TIMESTAMP by non-self users. Exits 0 when new feedback detected, exits 1 on timeout. Default: 10 min timeout, 30s interval.

Check New Feedback (Differential)

~/.claude/skills/pr-review/scripts/check-new-feedback.sh [PR_NUMBER] --since TIMESTAMP

Like check-pr-feedback.sh but only shows feedback created after TIMESTAMP , excluding self-posted comments. Use in loop mode to distinguish new from already-addressed feedback. Ends with a summary line: Summary: N conversation, M inline, K reviews .

Commit Workflows

Always use commit-and-push.sh for committing. It stages all changes, commits, pushes, and enforces branch safety (refuses main /master , never force-pushes).

~/.claude/skills/pr-review/scripts/commit-and-push.sh -m "<type>: <outcome>"

Commit Type Conventions

Types: feat , fix , refactor , docs , chore , test

Self-Check Before Commit

Before committing, verify:

• Test changes — Run project-specific tests (npm test , pytest , etc.) if modifying working code

• Check latest feedback — Run check-pr-feedback.sh to catch any new comments

• User confirmation — If user is active in session, ask before committing

• Verify claims — If Fix Report says "verified:", actually verify

PR Creation

Set Up Template (Once)

Create .github/pull_request_template.md :

Summary

How to test

Notes

• Review feedback may arrive in conversation comments, inline threads, or review submissions. Check all channels.

Or copy from assets/pr_template.md .

Create PR

Fill Summary, How to test, and Notes sections.

Code Review Coordination

Feedback Channels

Channel Reviewer Type Format

Conversation AI agents, humans Top-level comments

Inline Review bots (CodeRabbit, Gemini, Codex, Snyk, etc.), humans File/line threads

Reviews Humans, some bots Approve/Request Changes + optional body

Critical Rule: Check ALL Three Channels

~/.claude/skills/pr-review/scripts/check-pr-feedback.sh

Why: Different reviewers post in different channels. Missing any channel = missing feedback.

Three channels:

• Conversation comments — general discussion, agent reviews

• Inline comments — file/line-specific feedback from any reviewer

• Reviews — approval state + optional body

Critical Evaluation of Feedback

Never trust review feedback at face value. Before acting on any comment — whether from a human reviewer, review bot, or AI agent — critically evaluate it:

• Verify the claim — Read the actual code being referenced. Does the reviewer's description match reality? Reviewers (especially bots) may misread context, reference wrong lines, or describe code that doesn't exist.

• Check for hallucinations — Review bots may fabricate issues: non-existent variables, imagined type mismatches, phantom security vulnerabilities. Always confirm the issue exists before fixing it.

• Assess correctness — Even if the issue is real, the suggested fix may be wrong. Evaluate whether the suggestion would break existing behavior, introduce regressions, or conflict with project conventions.

• Test before committing — If a suggestion modifies working code, run tests before and after to confirm the change is actually an improvement.

If a review comment is incorrect, respond with a clear explanation of why rather than applying a bad fix. Use WONTFIX status with reasoning in the Fix Report.

Responding to Inline Comments

• Critically evaluate the feedback (see above), then address it in code if valid

• Reply inline to each comment (sign with agent identity):

Short messages — inline text:

~/.claude/skills/pr-review/scripts/reply-to-inline.sh <COMMENT_ID> "Fixed @ abc123. [details] —[Your Agent Name]"

Messages with ${...} or shell-sensitive syntax — write to file first, pass path:

~/.claude/skills/pr-review/scripts/reply-to-inline.sh <COMMENT_ID> .agents/scratch/reply.md

• Include in Fix Report (conversation comment) — the Fix Report summarizes all changes, but inline replies ensure each comment gets a direct acknowledgment

Invoking Review Agents

Run invoke-review-agents.sh when check-pr-feedback.sh returns empty output from all three channels — no feedback means no agents have reviewed yet.

No feedback on the PR? Invoke all agents:

~/.claude/skills/pr-review/scripts/invoke-review-agents.sh

User mentioned specific agents (e.g., "ask Gemini and Codex to review"):

~/.claude/skills/pr-review/scripts/invoke-review-agents.sh --agents gemini,codex

Agent selection from prompt: If the user's prompt names specific agents (e.g., "have Codex review this"), use --agents with the matching slug(s). Otherwise invoke all.

Embedding in PR body: When creating a new PR with create-pr.sh --invoke , trigger text is appended to the PR body automatically (via --format-only ). This avoids a separate trigger comment that would cause double-invocations when auto-review is enabled. Only use invoke-review-agents.sh directly when the PR already exists.

After invoking: Inform the user that trigger comments were posted and suggest running check-pr-feedback.sh again once agents have had time to respond (typically a few minutes).

See references/review-agents.md for the full agent registry and instructions for adding new agents.

Fix Reporting

After addressing feedback, always post ONE conversation comment (Fix Report). This is separate from requesting re-review — the Fix Report documents what was done, even if no re-review is needed.

Write the report with the agent's Write tool (e.g., to .agents/scratch/fix-report.md ), then post it:

~/.claude/skills/pr-review/scripts/post-fix-report.sh .agents/scratch/fix-report.md

Fix Report format:

Fix Report

• [file.ext:L10 Symbol]: FIXED @ abc123 — verified: npm test passes
• [file.ext:L42 fn]: WONTFIX — reason: intentional per AGENTS.md
• [file.ext:L100 class]: DEFERRED — tracking: #123
• [file.ext:L200 method]: QUESTION — Should this handle X?

Optionally, if re-review is needed, add @reviewer-username please re-review. at the end of the body.

Fix Statuses

Status Required Info

FIXED Commit hash + verification command/result

WONTFIX Reason (cite docs if applicable)

DEFERRED Issue/ticket link

QUESTION Specific question to unblock

See references/fix-report-examples.md for real-world examples.

Use assets/fix-report-template.md as starting point.

Review Format (For Agent-Reviewers)

Agent-reviewers MUST post ONE top-level conversation comment:

Review - Actionable Findings

Blocking

• path/file.ext:L10-L15 (Symbol): Issue → Fix → Verify: command

Optional

• path/file.ext:L100 (class): Improvement → Fix

Rules:

• Blocking MUST include verification (runnable command or objective check)

• Use file:line

• symbol anchor

• Actionable, not prose

• Group by severity

Do NOT:

• Create inline file/line comments

• Submit GitHub review submissions

• Post multiple separate comments

Why: Inline comments harder to retrieve. Conversation comments deterministic.

Re-Review Loop

After Fix Report:

• Request re-review: @reviewer please re-review. See Fix Report.

• Tag ALL reviewers who provided feedback

• If QUESTION items: Wait for clarification

• If blocking feedback was only provided inline: Mention it was addressed, optionally ask to mirror to conversation for future determinism

Loop Mode

Activate when the user's prompt requests a review loop, review cycle, or similar — in any words — meaning: run the full review-fix-review cycle autonomously until no new feedback remains.

Default max rounds: 5. Override with user instruction if needed.

Loop workflow:

• Branch — open-branch.sh (idempotent — creates branch if on main/master)

• PR — create-pr.sh --invoke --title "..." --body <path> — write body with agent Write tool, pass path. Capture output prefix (CREATED: / EXISTS: )

• Invoke — Round 1: if step 1 output CREATED: , skip (triggers in PR body). If EXISTS: , run invoke-review-agents.sh . Rounds 2+: agents triggered by @-mentions in previous Fix Report footer (no separate invoke step)

• Wait — wait-for-reviews.sh --since <timestamp> — use timestamp from get-context.sh (run after last commit, or after step 1 for round 1). Polls until new feedback or timeout

• Check — check-pr-feedback.sh (ALL feedback, all channels)

• Process — compare all feedback against previous Fix Reports. Address only: (a) items not covered in any Fix Report, (b) items with new follow-up comments after the last Fix Report. Critically evaluate each item before fixing

• Fix code, commit — commit-and-push.sh -m "fix: address review feedback round N"

• Get timestamp — get-context.sh (capture timestamp for next wait step)

• Reply inline — reply-to-inline.sh for each addressed inline comment; sign with agent identity; tag the reviewer's @github-user

• Fix Report — write report with agent Write tool, then post-fix-report.sh <PR> <path>

• Before max: footer has @-mentions + @coderabbitai review on its own line

• At max: footer has max-reached message (see below)

• Loop — if ROUND < MAX_ROUNDS , go to step 3

Why full check instead of differential: Using check-new-feedback.sh --since in the check step risks missing feedback that arrives during the fix phase (e.g., Gemini posts while agent is fixing Codex's comments). The full check + Fix Report comparison approach is gap-free.

Termination conditions (any):

• Step 5 finds nothing new to process (all feedback already addressed in Fix Reports)

• wait-for-reviews.sh times out (no new feedback after invocation)

• A reviewer posts an Approve review

• User explicitly stops the loop

• Max rounds reached

Final round Fix Report footer:

Max review rounds (N) reached. Remaining items addressed above. Manual re-review recommended.

Inline reply tagging: When replying to a bot/agent inline comment, include the reviewer's GitHub username in the reply (e.g., —Claude Sonnet 4.6 | addressed @gemini-code-assist feedback ).

See references/fix-report-examples.md Examples 7–8 for loop-mode Fix Reports.

Multi-Reviewer Patterns

Duplicate Feedback

If multiple reviewers flag the same issue:

• [file.php:L42 (ALL flagged)]: FIXED @ abc123 — verified: npm test passes
  • Gemini: "use const"
  • Codex: "prefer immutable"
  • Claude: "const prevents reassignment"

Conflicting Suggestions

• [file.php:L100]: QUESTION — Gemini suggests pattern A, Codex suggests pattern B. Which aligns with project conventions? See AGENTS.md.

Finding Comments by Reviewer

Use check-pr-feedback.sh — its output already includes [user.login] for every comment across all three channels. Filter the output for the reviewer you need:

~/.claude/skills/pr-review/scripts/check-pr-feedback.sh | grep "coderabbitai"

Troubleshooting

"Can't find review comments" → Check all three channels. Use ~/.claude/skills/pr-review/scripts/check-pr-feedback.sh , not just gh pr view .

"Reviewer posted inline, should I reply inline?" → Yes, always. Reply inline with a brief ack so the comment can be resolved in GitHub UI. Also include in Fix Report.

"Multiple reviewers flagged same issue" → Fix once, report once (note all sources), tag all reviewers.

"Conflicting suggestions" → Mark QUESTION, check project docs, cite specific suggestions.

"Script can't detect PR" → Run from repository root. Must be on branch with open PR.

"Reply script fails with HTTP 422" → Use -F in_reply_to=ID not --raw-field . The -F flag works correctly with gh CLI for numeric IDs.

"Review suggestion broke working code" → Never trust suggestions blindly. Verify the issue exists, evaluate the fix, and test before committing. Review bots frequently hallucinate problems or suggest incorrect fixes.

"No feedback on PR — all three channels empty" → Agents haven't reviewed yet. Run ~/.claude/skills/pr-review/scripts/invoke-review-agents.sh to trigger them, then wait and re-check.

"Committed before checking latest feedback" → Run feedback check script immediately before declaring PR "ready" or "complete."

Summary

Key principles:

• Always check all three channels (conversation + inline + reviews)

• Critically evaluate every comment — reviewers can be wrong, misread context, or hallucinate issues

• Any reviewer (human, bot, agent) can post in any channel

• One Fix Report per round

• Tag all reviewers explicitly

• If no feedback exists, invoke agents first — never declare a PR complete without at least one review round

Most common mistakes: ❌ Only checking conversation or gh pr view

✅ Always run ~/.claude/skills/pr-review/scripts/check-pr-feedback.sh

❌ Blindly applying review suggestions without verifying the issue exists ✅ Read the actual code, confirm the problem, test the fix