Review PR

!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config context --skill review-pr --fail-safe !${CLAUDE_PLUGIN_ROOT}/bin/accelerator config agents --fail-safe

If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher.

!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config review pr --fail-safe

PR reviews directory: !${CLAUDE_PLUGIN_ROOT}/bin/accelerator config path review_prs --fail-safe Tmp directory: !${CLAUDE_PLUGIN_ROOT}/bin/accelerator config path tmp --fail-safe

IMPORTANT: Wherever {tmp directory} or {pr reviews directory} appears in the instructions below, substitute the actual resolved path shown above. Never use /tmp or any other path not shown above.

IMPORTANT: When composing prompts for sub-agents, resolve all {...} path placeholders to their actual values before passing the prompt — sub-agents cannot see the bold-label definitions above and have no way to resolve the placeholders themselves.

PR Review Template

The template below defines the frontmatter and body structure that every PR review must carry. Read it now — use it to guide what information you record in Steps 3-4 and what shape you persist in Step 4.10.

!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config template pr-review --fail-safe

You are tasked with reviewing a pull request through multiple quality lenses and then presenting a compiled analysis of the code changes.

Initial Response

When this command is invoked:

1. Check if a PR number or URL was provided:

• If a PR number or URL was provided as an argument, identify the PR immediately
• If optional focus arguments were provided (e.g., "focus on security and architecture"), note them for lens selection
• Begin the review process

2. If no argument provided, respond with:

I'll help you review a pull request. Please provide:
1. The PR number or URL (or I'll check the current branch)
2. (Optional) Focus areas to emphasise (e.g., "focus on security and
   architecture")

Tip: You can invoke this command with arguments:
  `/review-pr 123`
  `/review-pr 123 focus on security and test coverage`

Then check if the current branch has a PR: gh pr view --json number,url,title,state 2>/dev/null

If a PR is found on the current branch, offer to review it. If not, wait for the user's input.

Available Review Lenses

Lens	Lens Skill	Focus
Architecture	architecture-lens	Modularity, coupling, dependency direction, structural drift
Security	security-lens	OWASP Top 10, input validation, auth/authz, secrets, data flows
Test Coverage	test-coverage-lens	Coverage adequacy, assertion quality, test pyramid, anti-patterns
Code Quality	code-quality-lens	Complexity, design principles, error handling, code smells
Standards	standards-lens	Project conventions, API standards, naming, accessibility
Usability	usability-lens	Developer experience, API ergonomics, configuration, onboarding
Performance	performance-lens	Algorithmic efficiency, resource usage, concurrency, caching
Documentation	documentation-lens	Documentation completeness, accuracy, audience fit
Database	database-lens	Migration safety, schema design, query correctness, integrity
Correctness	correctness-lens	Logical validity, boundary conditions, state management, concurrency
Compatibility	compatibility-lens	API contracts, cross-platform, protocol compliance, deps
Portability	portability-lens	Environment independence, deployment flexibility, vendor lock
Safety	safety-lens	Data loss prevention, operational safety, protective mechanisms

Process Steps

Step 1: Identify and Fetch the PR

1. Get PR metadata: gh pr view {number} --json number,url,title,state,baseRefName,headRefName

2. Create temp directory at {tmp directory}/pr-review-{number} (substituting the actual PR number):

   mkdir -p {tmp directory}/pr-review-{number}
   

3. Fetch diff, changed files, PR description, and commit context:

   gh pr diff {number} > {tmp directory}/pr-review-{number}/diff.patch
   gh pr diff {number} --name-only > {tmp directory}/pr-review-{number}/changed-files.txt
   gh pr view {number} --json body --jq '.body' > {tmp directory}/pr-review-{number}/pr-description.md
   gh pr view {number} --json commits --jq '.commits[].messageHeadline' > {tmp directory}/pr-review-{number}/commits.txt
   

4. Read the diff, changed files list, PR description, and commits to understand scope and intent.

5. Fetch additional metadata for the Reviews API:

   gh api repos/{owner}/{repo}/pulls/{number} --jq '.head.sha' > {tmp directory}/pr-review-{number}/head-sha.txt
   

   ${CLAUDE_PLUGIN_ROOT}/bin/accelerator collaboration pr base-repo {number} > {tmp directory}/pr-review-{number}/repo-info.txt
   

   Where {owner} and {repo} are extracted from the PR metadata already fetched in step 1.

Error handling: If any gh command fails, handle these cases:

• gh not installed or not authenticated: Inform the user that the gh CLI is required and suggest running gh auth login to authenticate.
• No default remote repository (gh-specific): Instruct the user to run gh repo set-default and select the appropriate repository (mirrors the pattern in /describe-pr) — this is gh's own default-repo setting, distinct from the collaboration binary's own origin-remote-based resolution below.
• Cannot determine base repo owner/name: If accelerator collaboration pr base-repo exits non-zero, surface its stderr verbatim (non-zero exit; exit code 2 for a usage/refusal such as no origin remote configured, 1 for any other failure, e.g. a GitHub API error).
• Invalid PR number or PR not found: Inform the user that the PR could not be found and suggest checking the number. If on a branch with no PR, list open PRs with gh pr list --limit 10 and ask the user to select one.
• Empty diff: If diff.patch is empty (e.g., a draft PR with no changes), inform the user and use the AskUserQuestion tool with two options:
  1. Yes, review description and commits only — proceed without a diff
  2. No, abort — exit without reviewing

Step 2: Select Review Lenses

Determine which lenses are relevant based on the PR's scope and any user-provided focus arguments.

If the user provided focus arguments:

• Map the focus areas to the corresponding lenses
• Include any additional lenses that are clearly relevant to the PR's scope
• Briefly explain which lenses you're running and why

If no focus arguments were provided, auto-detect relevance:

Take time to think carefully about which lenses apply based on:

• Architecture — relevant for most PRs; skip only for trivial single-file changes
• Security — relevant when changes involve: user input handling, auth/authz, data storage, external integrations, API endpoints, secrets/config
• Test Coverage — relevant for most PRs; skip only for documentation-only or configuration-only changes
• Code Quality — relevant for most PRs; skip only for documentation-only changes
• Standards — relevant when changes involve: API changes, new files/modules, public interfaces, naming-heavy changes
• Usability — relevant when changes involve: public APIs, CLI interfaces, configuration surfaces, breaking changes, developer-facing libraries
• Performance — relevant when changes involve: data processing, API endpoints handling load, algorithm-heavy code, concurrency resource efficiency, caching logic, or hot code paths. Skip for documentation-only, configuration-only, or simple UI changes.
• Documentation — relevant when changes involve: public APIs, README files, configuration surfaces, new features that need documentation, breaking changes requiring migration guides. Skip for internal refactoring with no interface changes.
• Database — relevant when changes involve: database migrations, schema changes, new queries, ORM model changes, transaction logic, connection pool configuration. Skip for changes with no database interaction.
• Correctness — relevant for most PRs; skip only for documentation-only, configuration-only, or simple renaming changes.
• Compatibility — relevant when changes involve: public API modifications, dependency updates, serialisation format changes, cross-platform code, protocol implementations. Skip for internal-only changes with no external consumers.
• Portability — relevant when changes involve: infrastructure configuration, deployment scripts, containerisation, cloud provider integrations, environment-specific code paths. Skip for application logic with no environment dependencies.
• Safety — relevant when changes involve: data deletion or modification operations, deployment configuration, automated batch processes, infrastructure changes, feature flags, or critical system components. Skip for read-only features, documentation, or UI-only changes.

Lens selection cap: Select the most relevant lenses for the change under review. If review configuration is provided above, use the configured min_lenses and max_lenses values. Otherwise, use the defaults: {min lenses} to {max lenses} lenses. Apply these prioritisation rules:

Apply this lens selection pipeline in order:

1. Start with all available lenses: the 13 built-in lenses plus any custom lenses listed in the review configuration above.
2. Remove disabled lenses: if review configuration specifies disabled_lenses, remove those from the available set. They are never selected regardless of auto-detect criteria.
3. Mark core lenses: if review configuration specifies core_lenses, use that list. Otherwise, the core lenses are Architecture, Code Quality, Test Coverage, and Correctness. Core lenses are included unless the change is clearly outside their scope.
4. Auto-detect remaining lenses: use the criteria below (for built-in lenses) and the auto-detect criteria from review configuration (for custom lenses) to identify which non-core lenses are relevant to the change. Custom lenses that provide auto-detect criteria participate in selection like any other non-core lens. Custom lenses without auto-detect criteria (marked "always include" in the configuration) are always selected. Custom lenses use absolute paths instead of the ${CLAUDE_PLUGIN_ROOT} lens path template.
5. Apply focus arguments: if the user provided focus areas, prioritise the corresponding lenses and fill remaining slots with auto-detected ones.
6. Cap at max_lenses: if more lenses than the configured maximum pass selection, rank by relevance and drop the least relevant. Prefer lenses whose core responsibilities directly overlap with the change's concerns.
7. Enforce min_lenses floor: never run fewer than min_lenses unless the change is trivially scoped.

When presenting the lens selection, clearly indicate which lenses are selected and which are skipped, with a brief reason for each skip.

Present lens selection to the user before proceeding:

Based on the PR's scope, I'll review through these lenses:
- Architecture: [reason]
- Security: [reason — or "Skipping: no security-sensitive changes identified"]
- Test Coverage: [reason]
- Code Quality: [reason]
- Standards: [reason — or "Skipping: ..."]
- Usability: [reason — or "Skipping: ..."]
- Performance: [reason — or "Skipping: no performance-sensitive changes identified"]
- Documentation: [reason — or "Skipping: ..."]
- Database: [reason — or "Skipping: no database changes identified"]
- Correctness: [reason]
- Compatibility: [reason — or "Skipping: ..."]
- Portability: [reason — or "Skipping: ..."]
- Safety: [reason — or "Skipping: ..."]

Then use the AskUserQuestion tool to ask the user whether to proceed, with two options:

1. Yes, use the proposed lenses — run the review with the selected lenses
2. No, specify which lenses to use — adjust the selection before running

Wait for the user's answer before spawning reviewers. If they choose option 2, ask which lenses they want using a plain-text question only — do NOT use AskUserQuestion for this follow-up (the lens list is too large for the 4-option limit). If any lens name is unrecognised, seek clarification. Once confirmed, update the selection and re-present it using the same AskUserQuestion proceed/adjust pattern. This loop is user-controlled with no hard termination limit.

Step 3: Spawn Review Agents

For each selected lens, spawn the {reviewer agent} agent with a prompt that includes paths to the lens skill and output format files. Do NOT read these files yourself — the agent reads them in its own context.

Reminder: In the template below, replace {tmp directory} with the actual path resolved at the top of this skill before passing the prompt to the agent.

Compose each agent's prompt following this template:

You are reviewing pull request changes through the [lens name] lens.

## Context

The PR artefacts are in the temp directory at {tmp directory}/pr-review-{number}:
- `diff.patch` — the full diff
- `changed-files.txt` — list of changed file paths
- `pr-description.md` — PR description
- `commits.txt` — commit messages

PR number: [number]

## Analysis Strategy

1. Read your lens skill and output format files (see paths below)
2. Read `diff.patch` and `changed-files.txt` from the temp directory
3. Read `pr-description.md` and `commits.txt` for intent context
4. Explore the codebase to understand the architectural landscape around
   the changes
5. Evaluate the changes through your lens, applying each key question
6. Identify beyond-the-diff impact — trace how changes affect consumers
7. Anchor findings to precise diff line numbers (lines must be within
   diff hunks)

## Lens

Read the lens skill at the path listed in the Lens Catalogue table in the
review configuration above. If no review configuration is present, use:
${CLAUDE_PLUGIN_ROOT}/skills/review/lenses/[lens]-lens/SKILL.md

## Output Format

Read the output format at: ${CLAUDE_PLUGIN_ROOT}/skills/review/output-formats/pr-review-output-format/SKILL.md

IMPORTANT: Return your analysis as a single JSON code block. Do not include
prose outside the JSON block.

Spawn all selected agents in parallel using the Task tool with subagent_type: "!${CLAUDE_PLUGIN_ROOT}/bin/accelerator config agent reviewer --fail-safe".

IMPORTANT: Wait for ALL review agents to complete before proceeding.

Handling malformed agent output:

If an agent's response is not a clean JSON block, apply this extraction strategy:

1. Look for a JSON code block fenced with triple backticks (optionally with a json language tag)
2. If found, extract and parse the content within the fences
3. If the extracted JSON is valid, use it normally
4. If no JSON code block is found, or the JSON within it is invalid, apply the fallback: treat the agent's entire output as a single general finding with the agent's lens name and "major" severity, and include it in the review summary body

When falling back, warn the user that the agent's output could not be parsed and present the raw agent output in a collapsed form so the user can see what the agent actually found.

Step 4: Aggregate and Curate Findings

Once all reviews are complete:

1. Parse agent outputs: Extract the JSON block from each agent's response (see the extraction strategy in Step 3). Collect the summary, strengths, comments, and general_findings arrays from each.

2. Aggregate across agents:

   • Combine all comments arrays into a single list
   • Combine all general_findings arrays into a single list
   • Combine all strengths arrays into a single list
   • Collect all summary strings

3. Validate line numbers against the diff: Parse the hunk headers in diff.patch to build valid line ranges per file. For each @@ header:

   • Extract the new-file range from @@ -a,b +c,d @@ — lines c through c+d-1 are valid RIGHT-side lines
   • Extract the old-file range — lines a through a+b-1 are valid LEFT-side lines
   • For each comment in the aggregated comments list, check that its path/line/side falls within a valid range for that file
   • Move any comments with out-of-range lines to general_findings automatically, preserving all their metadata (severity, lens, title, body)
   • If a comment was moved, note it in the preview so the user knows

4. Deduplicate inline comments: Where multiple agents flag the same file, same side, and overlapping or adjacent line range (same path, lines within the configured dedup proximity ({dedup proximity}) of each other), consider merging — but only when the findings address the same underlying concern from different lens perspectives. Spatial proximity alone is not sufficient; the findings must be semantically related.

   When merging:

   • Combine the bodies, attributing each part to its lens
   • Use the highest severity among the merged findings
   • Use the highest confidence among the merged findings
   • Note all contributing lenses in the title

   When in doubt, keep comments separate — distinct inline comments are easier to resolve individually on GitHub than a merged comment covering multiple concerns.

5. Prioritise and cap inline comments:

   • Sort by severity: critical > major > minor > suggestion
   • Within the same severity, sort by confidence: high > medium > low
   • Always include all critical findings, even if that exceeds {max inline comments}
   • Select up to the configured max inline comments ({max inline comments}) comments total for inline posting (more if all critical findings push beyond the cap)
   • Move any remaining comments to the summary body as an "Additional Findings" list (title + file:line only)

6. Determine suggested verdict:

   If review configuration provides verdict overrides above, apply those thresholds instead of the defaults below:

   • If pr_request_changes_severity is none, skip this rule (never suggest REQUEST_CHANGES based on severity)
   • If any findings at or above the configured pr_request_changes_severity (default: critical) exist → suggest REQUEST_CHANGES
   • If only findings below that threshold → suggest COMMENT
   • If no findings at all (only strengths) → suggest APPROVE

7. Identify cross-cutting themes: Look for findings that appear across multiple lenses — issues flagged by 2+ agents reinforce each other and should be highlighted in the summary. Also identify tradeoffs where different lenses conflict (e.g., security wants more validation, usability wants less friction).

8. Compose the review summary body (this becomes the body field of the GitHub review):

   ## Code Review: #{number} - {title}
   
   **Verdict:** [APPROVE | REQUEST_CHANGES | COMMENT]
   
   [Combined assessment: take each agent's summary and synthesise into 2-3
   sentences covering the overall quality of the PR across all lenses]
   
   ### Cross-Cutting Themes
   [Issues that multiple lenses identified — these deserve the most attention]
   - **[Theme]** (flagged by: [lenses]) — [description]
   
   ### Tradeoff Analysis
   [Where different lenses disagree, present both perspectives]
   - **[Quality A] vs [Quality B]**: [description and recommendation]
   
   [Omit either section if there are no cross-cutting themes or tradeoffs]
   
   ### Strengths
   - ✅ [Aggregated and deduplicated strengths from all agents]
   
   ### General Findings
   - [emoji] **[Lens]**: [General findings from all agents, sorted by severity]
   
   ### Additional Findings
   [Only if more than {max inline comments} inline comments were produced and
   some were deferred]
   - [emoji] `file:line` — [title] ([lens])
   
   ---
   *Review generated by /review-pr*
   

9. Compose each inline comment body: Each comment's body field should already be self-contained from the agent output. For merged comments, combine the bodies with a blank line separator and attribute each section to its lens.

10. Write the review artifact to {pr reviews directory}/:

    Determine the next review number:

    mkdir -p {pr reviews directory}
    # Glob for existing reviews of this PR
    ls {pr reviews directory}/{number}-review-*.md 2>/dev/null
    # Extract the highest number, increment by 1. If none exist, use 1.
    

    Write the review document to {pr reviews directory}/{number}-review-{N}.md.

Populate frontmatter

The target: field is filled automatically from the PR number — this is what makes the review traceable back to the PR it covers. Per ADR-0034, the typed-linkage form is "pr:<pr-number>".

Before writing the PR review file, capture metadata and substitute the unified base fields and per-type extras into the template's frontmatter block:

1. Invoke ${CLAUDE_PLUGIN_ROOT}/bin/accelerator corpus metadata derive to obtain Current Date/Time (UTC):.
2. Substitute every field below with the indicated value:
   • type: ← pr-review
   • id: ← {number}-review-{N} (the review filename stem, where {number} is the PR number and {N} is the next review number), always quoted as a YAML string
   • title: ← the PR title from gh pr view --json title
   • date: ← the Current Date/Time (UTC): value
   • author: ← the author value resolved per create-work-item/SKILL.md:578-580
   • producer: ← review-pr
   • status: ← complete
   • last_updated: ← the same Current Date/Time (UTC): value
   • last_updated_by: ← the same value resolved for author
   • schema_version: ← 1 (bare integer, not quoted)
   • parent: ← typed-linkage ref to the parent PR ("pr:NNNN"). Fill when the review names a parent; otherwise omit the key.
   • target: ← "pr:<pr-number>" (e.g. "pr:123"); the typed-linkage ref to the PR under review per ADR-0034, must match the regex ^"pr:[0-9]+"$. Always fill — every review has a target.
   • relates_to: ← list of typed-linkage refs to related reviews or artifacts (["pr-review:NNNN", ...]). Fill when prior reviews are explicit; otherwise omit the key.
   • reviewer: ← the reviewer value resolved per create-work-item/SKILL.md:578-580
   • verdict: ← the verdict from Step 4.6 (APPROVE | REQUEST_CHANGES | COMMENT)
   • lenses: ← the list of lens names used
   • review_number: ← N (the next available review number from the glob above)
   • pr_number: ← the PR number from gh pr view --json number (bare integer; foreign reference to the external PR per ADR-0033 §Identity-value shape contract)