Pr Review

PR Review Orchestrator

Evidence-based PR review workflow with self-audit for quality control.

Invocation

/pr-review owner/repo#123
/pr-review https://github.com/owner/repo/pull/123
/pr-review 123                    # Uses current repo
/pr-review 123 --issue https://github.com/owner/repo/issues/456
/pr-review 123 --post-comment     # Post a human-readable comment after final_review
/pr-review 123 --show-xml         # Also print XML phase artifacts (debug)

Workflow Overview

Phase 0 (fetch) ──┬──► Phase 1 (evidence) ──┬──► Phase 3 (review + scope/verification triage) ──► Phase 4 (audit) ──► Phase 5 (finalize) ──► Phase 6 (render) ──► Phase 7 (comment) ──► Phase 8 (summary)
                  └──► Phase 2 (requirements)┘

Parallelization: Phases 1 and 2 run in parallel after Phase 0 completes.

Execution

Step 1: Parse Input

Extract from user input:

• owner: Repository owner (default: current repo owner)
• repo: Repository name (default: current repo)
• pr_number: PR number
• issue_url: Optional linked issue URL
• post_comment: Optional flag or explicit user request to publish a GitHub comment
• show_xml: Optional flag to print XML phase artifacts

Step 2: Phase 0 - Fetch PR Data

Use gh CLI to fetch PR data:

# Get PR metadata
gh pr view {pr_number} --repo {owner}/{repo} --json title,body,author,state,baseRefName,headRefName,files,additions,deletions

# Get PR diff
gh pr diff {pr_number} --repo {owner}/{repo}

# Get linked issues (parse from PR body for "Fixes #X", "Closes #X", etc.)
gh issue view {issue_number} --repo {owner}/{repo} --json title,body

Save <retrieval_plan> to an artifacts file. If --show-xml is set, also output <retrieval_plan> immediately.

Step 3: Phases 1 & 2 - Extract Evidence and Requirements (Parallel)

Spawn two subagents in parallel using Task tool with a single message containing both calls:

Task 1: Evidence Extraction

Task tool:
  subagent_type: "pr-evidence"
  description: "Extract PR evidence"
  prompt: "Extract evidence from PR #{pr_number} in {owner}/{repo}.
           Here is the diff: {diff_content}
           Output an <evidence_pack> XML artifact."

Task 2: Requirements Extraction

Task tool:
  subagent_type: "pr-requirements"
  description: "Extract requirements"
  prompt: "Extract requirements from issue {issue_url}.
           Output a <requirements_pack> XML artifact."

Both agents run in parallel. Wait for both to complete before proceeding.

Step 4: Phase 3 - Draft Technical Review

After both Phase 1 and Phase 2 complete:

• Input: <evidence_pack> + <requirements_pack>
• Apply all rules from references/global-rules.md
• Follow examples in references/examples.md
• Output format: See Phase 3 in references/phases.md
• Output <draft_review> when complete

Before writing blockers, suggestions, or tasks, run two gates on every candidate issue:

• Scope gate: Keep only findings tied to the linked issue's acceptance criteria/constraints/non-goals, the PR's stated purpose, the touched behavior, or a credible regression introduced by the changed boundary.
• Verification gate: Keep a finding only if the issue is supported by concrete evidence (citation plus code path, repro, failing validation, or explicit missing artifact). If scope is unclear or verification is weak, move it to questions_for_author or a validation task instead of escalating it.

Out-of-scope example:

• A PR that adds a refresh button can be reviewed for whether the button works, regresses existing behavior, or violates stated performance requirements.
• Asking the author to add a brand-new diagnostic page to measure refresh speed is out of scope unless the linked issue or PR explicitly includes observability/performance instrumentation work.

Required elements:

• Summary with "Key design decisions" bullet (citations required)
• <logical_impact_sweep> with startup/failure/lifecycle findings (citations required)
• <likely_regressions> with 1-3 testable scenarios
• <evidence_confidence> separating code-read confidence from runtime validation status
• All blockers, non-blocking suggestions, and actionable tasks must pass the scope gate and verification gate
• <actionable_outcomes> with 3-8 prioritized tasks
• <merge_recommendation> with rationale

Step 5: Phase 4 - Self-Audit

Spawn the pr-audit agent to audit the draft review:

Task tool:
  subagent_type: "pr-audit"
  description: "Audit draft review"
  prompt: "Audit this draft review for false positives, scope drift, and overstated claims.

           <draft_review>
           {draft_review_content}
           </draft_review>

           <requirements_pack>
           {requirements_pack_content}
           </requirements_pack>

           <pr_diff>
           {diff_content}
           </pr_diff>

           Output an <audit_report> XML artifact."

The audit checks for:

1. Language violations (forbidden words without basis)
2. Missing citations
3. Speculation presented as fact
4. Quantifier violations
5. Terminology imprecision
6. Unrealistic test suggestions
7. Missing critical findings
8. Evidence-basis misuse (code-read vs tests-run)
9. Scope drift (reviewer asks for work outside issue/PR scope)
10. Verification gaps (claims escalated without enough evidence)
11. Approval-gate failures (unverified compatibility/risk-relevant runtime validation)

Step 6: Phase 5 - Finalize Review

• Input: <draft_review> + <audit_report>
• Apply all <required_edits> from audit
• Verify all claims have proper citations and basis tags
• Verify blockers, suggestions, and tasks still stay within scope after edits
• Verify merge recommendation still satisfies approval gates after edits
• Output format: See Phase 5 in references/phases.md
• Output <final_review> as last artifact

Step 7: Phase 6 - Render Human Review (Required)

After Phase 5 completes, render a human-readable Markdown review from the <final_review> XML and output the Markdown (no XML):

python /codex/skills/pr-review-comment/scripts/post_comment.py --pr {owner}/{repo}#{pr_number} --print-only <<'XML'
{final_review_content}
XML

If --show-xml is set, also output <final_review> before the Markdown (useful for debugging).

Step 8: Phase 7 - Publish Comment (Optional)

If the user or orchestrator requests posting a human-readable comment:

• Input: <final_review>
• Convert to Markdown and post using:

python /codex/skills/pr-review-comment/scripts/post_comment.py --pr {owner}/{repo}#{pr_number} <<'XML'
{final_review_content}
XML

• If --show-xml is set, output <comment_posted> with status and error if posting fails; otherwise, output a single plain-text line: Comment posted: <success|failed|skipped>.

Step 9: Phase 8 - Human Summary (Required)

After Phase 7 completes, invoke the pr-review-summary skill with the <final_review> XML. Output the summary as plain text with no XML tags. This step is mandatory even if comment posting is skipped.

Output Streaming

By default, do not output XML artifacts. Write them to an artifacts directory (for example: /codex/working/pr-review/{owner}-{repo}#{pr_number}/), and only output:

1. Markdown review (from Phase 6 render; no XML)
2. Short human summary (Phase 8; no XML)

If --show-xml is set, also output each XML artifact as soon as its phase completes:

1. <retrieval_plan> - After Phase 0
2. <evidence_pack> - After Phase 1
3. <requirements_pack> - After Phase 2
4. <draft_review> - After Phase 3
5. <audit_report> - After Phase 4
6. <final_review> - After Phase 5
7. <comment_posted> - After Phase 7 (or skipped)

Then output the Markdown review + short human summary as usual.

Available Agents

This skill uses three custom agents defined in .claude/agents/:

When spawning agents via Task tool, always include the input data they need (diff, issue URL, prior phase outputs).

Error Handling

• If PR fetch fails: Save details in the artifacts; with --show-xml, include the failure in <retrieval_plan>, otherwise print a plain-text error and continue with partial data.
• If issue not found: Save details in the artifacts; with --show-xml, output <requirements_pack><error>No linked issue found</error></requirements_pack>, otherwise proceed and note it in the Markdown review.
• If subagent fails: Record the error in that phase’s artifact; with --show-xml, also print that artifact.
• If comment posting fails: With --show-xml, output <comment_posted> with <status>failed</status> and an <error> message; otherwise print Comment posted: failed with the error.

References

• Global Rules - Language controls, citation requirements, basis tags
• Phase Definitions - Detailed output formats for each phase
• Examples - Good/bad examples and priority/effort definitions