Review PR
!accelerator config context --skill review-pr --fail-safe
!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.
!accelerator config review pr --fail-safe
PR reviews directory: !accelerator config path review_prs --fail-safe
Tmp directory: !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.
!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:
- 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
- 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
Get PR metadata:
gh pr view {number} --json number,url,title,state,baseRefName,headRefName
Create temp directory at {tmp directory}/pr-review-{number} (substituting
the actual PR number):
mkdir -p {tmp directory}/pr-review-{number}
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
Read the diff, changed files list, PR description, and commits to
understand scope and intent.
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
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:
- Yes, review description and commits only — proceed without a diff
- 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:
- Start with all available lenses: the 13 built-in lenses plus any
custom lenses listed in the review configuration above.
- Remove disabled lenses: if review configuration specifies
disabled_lenses, remove those from the available set. They are never
selected regardless of auto-detect criteria.
- 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.
- 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.
- Apply focus arguments: if the user provided focus areas, prioritise
the corresponding lenses and fill remaining slots with auto-detected ones.
- 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.
- 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:
- Yes, use the proposed lenses — run the review with the selected lenses
- 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: "!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:
- Look for a JSON code block fenced with triple backticks (optionally with
a
json language tag)
- If found, extract and parse the content within the fences
- If the extracted JSON is valid, use it normally
- 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:
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.
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
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
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.
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)
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
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).
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*
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.
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:
Invoke accelerator corpus metadata derive
to obtain Current Date/Time (UTC):.
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)
The PR title is recorded in the base title: field; no separate
pr_title: field is emitted (the unified schema uses the base
title: for all artifact titles per ADR-0033). The review_pass:
field is intentionally absent — review-pr has no in-place
re-review update flow today; re-running it produces a fresh
-review-{N+1}.md.
Write the file with the substituted frontmatter block, followed by
the review summary composed in Step 4.8 and the inline comments
and per-lens results sections:
{The full review summary from Step 4.8}
## Inline Comments
### `{path}:{line}` — {title}
**Severity**: {severity} | **Confidence**: {confidence} | **Lens**: {lens}
{comment body}
---
### `{path}:{line}` — {title}
...
## Per-Lens Results
### {Lens 1 Name}
**Summary**: {agent summary}
**Strengths**:
{agent strengths}
**Comments**:
{agent comments — each with path, line, severity, confidence, and body}
**General Findings**:
{agent general findings}
### {Lens 2 Name}
...
This review artifact captures the complete analysis. The GitHub review
(posted in Step 6) may be a curated subset (capped at ~{max inline comments}
inline comments), but the persistent artifact retains everything.
Step 5: Present the Review
Present a two-part preview showing exactly what will be posted to the PR:
Part 1: Review summary (will become the review's body):
Show the composed summary from Step 4.8 in a markdown code block so the user
can see exactly what will be posted.
Part 2: Inline comments (will be attached to specific diff lines):
## Proposed Inline Comments ([count] comments)
### [file path 1]
- Line [N]: [emoji] **[Lens]** — [title]
> [First 1-2 sentences of body as preview]
- Lines [N-M]: [emoji] **[Lens]** — [title]
> [First 1-2 sentences of body as preview]
### [file path 2]
- Line [N]: [emoji] **[Lens]** — [title]
> [First 1-2 sentences of body as preview]
[If comments were deferred due to the ~{max inline comments} cap:]
### Deferred to summary ([count] findings)
- [emoji] [Lens]: [title] — `file:line`
Step 6: Offer Actions
After presenting the preview:
The review is ready. Would you like to:
1. Post the review? (summary + [count] inline comments, verdict: [suggested verdict])
2. Change the verdict? (currently: [suggested verdict])
3. Edit or remove specific inline comments before posting?
4. Discuss any findings in more detail?
5. Re-run specific lenses with adjusted focus?
When the user chooses to post (option 1):
Read the HEAD SHA and repo info from the temp directory at
{tmp directory}/pr-review-{number}/head-sha.txt and
{tmp directory}/pr-review-{number}/repo-info.txt using the Read tool.
Construct the review payload as a JSON object containing:
commit_id: the HEAD SHA
body: the review summary composed in Step 4.8
event: the verdict ("COMMENT", "REQUEST_CHANGES", or "APPROVE")
comments: array of inline comment objects, each with:
path: file path from the agent's comment
line: line number from the agent's comment
side: side from the agent's comment
body: the self-contained comment body
start_line and start_side: included only if end_line is not null.
For multi-line comments, the agent's fields map to the API's fields
with an inversion (see "Multi-Line Comment API Mapping" in Phase 1):
- API
start_line ← agent's line (the beginning of the range)
- API
start_side ← agent's side
- API
line ← agent's end_line (the end of the range)
- API
side ← agent's side
Example: agent {line: 10, end_line: 15, side: "RIGHT"} becomes
API {start_line: 10, start_side: "RIGHT", line: 15, side: "RIGHT"}
Write the review payload JSON to
{tmp directory}/pr-review-{number}/review-payload.json, then post the
review:
gh api repos/{owner}/{repo}/pulls/{number}/reviews \
--method POST --input {tmp directory}/pr-review-{number}/review-payload.json
Where {owner}/{repo} are the values read from repo-info.txt.
Confirm success and show the PR URL:
gh pr view {number} --json url --jq '.url'
If the API returns a 422 error (typically an invalid line reference or
stale commit):
- Report the error to the user
- If the error indicates an invalid line reference, identify which comment(s)
caused the failure and offer to retry without them (move them to the summary)
- If the error indicates a stale
commit_id (the PR's HEAD has changed since
the review started), re-fetch the HEAD SHA and warn the user that new commits
were pushed. Offer to retry with the updated SHA, noting that line numbers
may have shifted and some comments may now be invalid
When the user chooses to edit comments (option 3):
- Present each comment with a number
- Allow the user to remove specific comments by number
- Allow the user to edit a comment's body text
- After edits, re-present the preview and offer the same action options
When the user changes the verdict (option 2):
- Use the
AskUserQuestion tool with three options:
- APPROVE — approve the PR
- COMMENT — leave a non-blocking comment review
- REQUEST_CHANGES — request changes before merge
- Update the summary body and re-present the preview
Important Guidelines
Read the diff before doing anything else — you need complete context to
select lenses and brief the agents properly
Spawn agents in parallel — the review lenses are independent and should
run concurrently for efficiency
Synthesise, don't concatenate — your value is in compiling a balanced
view across lenses, identifying themes and tradeoffs, and prioritising
actionable recommendations. Don't just paste seven reports together.
Be balanced — highlight strengths alongside concerns. A PR that makes
good architectural decisions but has security gaps should get credit for
both.
Prioritise by impact — structural issues that are hard to fix later
matter more than surface-level concerns. A critical finding from one lens
outweighs minor findings from all seven.
Respect tradeoffs — when lenses conflict, present both sides and let the
user decide. Don't privilege one quality attribute over another without
justification.
Clean up temp directory only at session end — agents may need to
re-reference the PR context during follow-up discussion.
The {tmp directory}/pr-review-{number}/ directory contains ephemeral
working data (diff, changed-files, PR description, commits, head SHA,
repo info, review payload JSON) used during the review session. The review
itself (summary, inline comments, per-lens results) is persisted separately
to {pr reviews directory}/{number}-review-{N}.md.
Handle API errors gracefully — if the review post fails due to invalid
line references, identify the problematic comments and offer to retry
without them rather than failing entirely
Cap inline comments — if agents produce more findings, prioritise
critical and major severity. Use the configured max ({max inline comments}).
Always include all critical findings even if that exceeds the cap. Move
overflow to the summary body. This prevents PR comment spam.
Keep positive feedback in the summary — strengths and good observations
go in the review body, never as inline comments. Inline comments are
exclusively for actionable findings.
Use emoji severity prefixes consistently — 🔴 critical, 🟡 major,
🔵 minor/suggestion, ✅ strengths. IMPORTANT: Use the actual Unicode
emoji characters (🔴 🟡 🔵 ✅), NOT text shortcodes like :red_circle:,
:yellow_circle:, :blue_circle:, or :white_check_mark:. Shortcodes
are not rendered in markdown and will appear as literal text.
What NOT to Do
- Don't skip writing the review artifact — always persist to
{pr reviews directory}/ so the full analysis is available to the team
- Don't post inline comments for positive feedback — strengths go in the
summary only
- Don't post more than the configured max inline comments
({max inline comments}) inline comments — prioritise by severity (always
include all critical findings even if that exceeds the cap)
- Don't post generic or vague inline comments — each must be specific and
actionable
- Don't skip the preview step — always show the user what will be posted
before posting
- Don't skip the lens selection step — always confirm with the user which
lenses will run
- Don't present raw agent output — always aggregate and curate into the
structured format
- Don't run lenses that clearly aren't relevant
- Don't modify any code — this is a read-only review
Relationship to Other Commands
The PR review sits in the development lifecycle alongside other commands:
/create-plan — Create the implementation plan
/review-plan — Review and iterate the plan quality
/implement-plan — Execute the approved plan
/validate-plan — Verify implementation matches the plan
/describe-pr — Generate PR description
/review-pr — Review the PR through quality lenses (this command)
!accelerator config instructions review-pr --fail-safe
1---2name: review-pr3description: Review a pull request through multiple quality lenses and present a compiled analysis with inline comments. Use when the user wants a thorough PR review.4---56# Review PR78!`accelerator config context --skill review-pr --fail-safe`9!`accelerator config agents --fail-safe`1011If no "Agent Names" section appears above, use these defaults:12accelerator:reviewer, accelerator:codebase-locator,13accelerator:codebase-analyser, accelerator:codebase-pattern-finder,14accelerator:documents-locator, accelerator:documents-analyser,15accelerator:web-search-researcher.1617!`accelerator config review pr --fail-safe`1819**PR reviews directory**: !`accelerator config path review_prs --fail-safe`20**Tmp directory**: !`accelerator config path tmp --fail-safe`2122**IMPORTANT**: Wherever `{tmp directory}` or `{pr reviews directory}` appears23in the instructions below, substitute the actual resolved path shown above.24Never use `/tmp` or any other path not shown above.2526**IMPORTANT**: When composing prompts for sub-agents, resolve all `{...}`27path placeholders to their actual values before passing the prompt —28sub-agents cannot see the bold-label definitions above and have no way to29resolve the placeholders themselves.3031## PR Review Template3233The template below defines the frontmatter and body structure that every34PR review must carry. Read it now — use it to guide what information35you record in Steps 3-4 and what shape you persist in Step 4.10.3637!`accelerator config template pr-review --fail-safe`3839You are tasked with reviewing a pull request through multiple quality lenses40and then presenting a compiled analysis of the code changes.4142## Initial Response4344When this command is invoked:45461. **Check if a PR number or URL was provided**:4748- If a PR number or URL was provided as an argument, identify the PR49 immediately50- If optional focus arguments were provided (e.g., "focus on security and51 architecture"), note them for lens selection52- Begin the review process53542. **If no argument provided**, respond with:5556```57I'll help you review a pull request. Please provide:581. The PR number or URL (or I'll check the current branch)592. (Optional) Focus areas to emphasise (e.g., "focus on security and60 architecture")6162Tip: You can invoke this command with arguments:63 `/review-pr 123`64 `/review-pr 123 focus on security and test coverage`65```6667Then check if the current branch has a PR:68`gh pr view --json number,url,title,state 2>/dev/null`6970If a PR is found on the current branch, offer to review it. If not, wait for71the user's input.7273## Available Review Lenses7475| Lens | Lens Skill | Focus |76|--------------------|-------------------------------|------------------------------------------------------------------------|77| **Architecture** | `architecture-lens` | Modularity, coupling, dependency direction, structural drift |78| **Security** | `security-lens` | OWASP Top 10, input validation, auth/authz, secrets, data flows |79| **Test Coverage** | `test-coverage-lens` | Coverage adequacy, assertion quality, test pyramid, anti-patterns |80| **Code Quality** | `code-quality-lens` | Complexity, design principles, error handling, code smells |81| **Standards** | `standards-lens` | Project conventions, API standards, naming, accessibility |82| **Usability** | `usability-lens` | Developer experience, API ergonomics, configuration, onboarding |83| **Performance** | `performance-lens` | Algorithmic efficiency, resource usage, concurrency, caching |84| **Documentation** | `documentation-lens` | Documentation completeness, accuracy, audience fit |85| **Database** | `database-lens` | Migration safety, schema design, query correctness, integrity |86| **Correctness** | `correctness-lens` | Logical validity, boundary conditions, state management, concurrency |87| **Compatibility** | `compatibility-lens` | API contracts, cross-platform, protocol compliance, deps |88| **Portability** | `portability-lens` | Environment independence, deployment flexibility, vendor lock |89| **Safety** | `safety-lens` | Data loss prevention, operational safety, protective mechanisms |9091## Process Steps9293### Step 1: Identify and Fetch the PR94951. **Get PR metadata**:96 `gh pr view {number} --json number,url,title,state,baseRefName,headRefName`97982. **Create temp directory** at `{tmp directory}/pr-review-{number}` (substituting99 the actual PR number):100 ```bash101 mkdir -p {tmp directory}/pr-review-{number}102 ```1031043. **Fetch diff, changed files, PR description, and commit context**:105 ```bash106 gh pr diff {number} > {tmp directory}/pr-review-{number}/diff.patch107 gh pr diff {number} --name-only > {tmp directory}/pr-review-{number}/changed-files.txt108 gh pr view {number} --json body --jq '.body' > {tmp directory}/pr-review-{number}/pr-description.md109 gh pr view {number} --json commits --jq '.commits[].messageHeadline' > {tmp directory}/pr-review-{number}/commits.txt110 ```1111124. **Read the diff, changed files list, PR description, and commits** to113 understand scope and intent.1141155. **Fetch additional metadata for the Reviews API**:116 ```bash117 gh api repos/{owner}/{repo}/pulls/{number} --jq '.head.sha' > {tmp directory}/pr-review-{number}/head-sha.txt118 ```119 ```bash120 accelerator collaboration pr base-repo {number} > {tmp directory}/pr-review-{number}/repo-info.txt121 ```122123 Where `{owner}` and `{repo}` are extracted from the PR metadata already124 fetched in step 1.125126**Error handling**: If any `gh` command fails, handle these cases:127128- **`gh` not installed or not authenticated**: Inform the user that the `gh`129 CLI is required and suggest running `gh auth login` to authenticate.130- **No default remote repository (`gh`-specific)**: Instruct the user to run131 `gh repo set-default` and select the appropriate repository (mirrors the132 pattern in `/describe-pr`) — this is `gh`'s own default-repo setting,133 distinct from the `collaboration` binary's own `origin`-remote-based134 resolution below.135- **Cannot determine base repo owner/name**: If `accelerator collaboration136 pr base-repo` exits non-zero, surface its stderr verbatim (non-zero exit;137 exit code 2 for a usage/refusal such as no `origin` remote configured,138 1 for any other failure, e.g. a GitHub API error).139- **Invalid PR number or PR not found**: Inform the user that the PR could not140 be found and suggest checking the number. If on a branch with no PR, list141 open PRs with `gh pr list --limit 10` and ask the user to select one.142- **Empty diff**: If `diff.patch` is empty (e.g., a draft PR with no changes),143 inform the user and use the `AskUserQuestion` tool with two options:144 1. **Yes, review description and commits only** — proceed without a diff145 2. **No, abort** — exit without reviewing146147### Step 2: Select Review Lenses148149Determine which lenses are relevant based on the PR's scope and any150user-provided focus arguments.151152**If the user provided focus arguments:**153154- Map the focus areas to the corresponding lenses155- Include any additional lenses that are clearly relevant to the PR's scope156- Briefly explain which lenses you're running and why157158**If no focus arguments were provided, auto-detect relevance:**159160Take time to think carefully about which lenses apply based on:161162- **Architecture** — relevant for most PRs; skip only for trivial single-file163 changes164- **Security** — relevant when changes involve: user input handling, auth/authz,165 data storage, external integrations, API endpoints, secrets/config166- **Test Coverage** — relevant for most PRs; skip only for documentation-only167 or configuration-only changes168- **Code Quality** — relevant for most PRs; skip only for documentation-only169 changes170- **Standards** — relevant when changes involve: API changes, new files/modules,171 public interfaces, naming-heavy changes172- **Usability** — relevant when changes involve: public APIs, CLI interfaces,173 configuration surfaces, breaking changes, developer-facing libraries174- **Performance** — relevant when changes involve: data processing, API175 endpoints handling load, algorithm-heavy code, concurrency resource176 efficiency, caching logic, or hot code paths. Skip for documentation-only,177 configuration-only, or simple UI changes.178- **Documentation** — relevant when changes involve: public APIs, README179 files, configuration surfaces, new features that need documentation,180 breaking changes requiring migration guides. Skip for internal refactoring181 with no interface changes.182- **Database** — relevant when changes involve: database migrations, schema183 changes, new queries, ORM model changes, transaction logic, connection184 pool configuration. Skip for changes with no database interaction.185- **Correctness** — relevant for most PRs; skip only for documentation-only,186 configuration-only, or simple renaming changes.187- **Compatibility** — relevant when changes involve: public API188 modifications, dependency updates, serialisation format changes,189 cross-platform code, protocol implementations. Skip for internal-only190 changes with no external consumers.191- **Portability** — relevant when changes involve: infrastructure192 configuration, deployment scripts, containerisation, cloud provider193 integrations, environment-specific code paths. Skip for application logic194 with no environment dependencies.195- **Safety** — relevant when changes involve: data deletion or modification196 operations, deployment configuration, automated batch processes,197 infrastructure changes, feature flags, or critical system components.198 Skip for read-only features, documentation, or UI-only changes.199200**Lens selection cap:** Select the most relevant lenses for the change under201review. If review configuration is provided above, use the configured202`min_lenses` and `max_lenses` values. Otherwise, use the defaults: 203**{min lenses} to {max lenses}** lenses. Apply these prioritisation rules:204205Apply this lens selection pipeline in order:2062071. **Start with all available lenses**: the 13 built-in lenses plus any208 custom lenses listed in the review configuration above.2092. **Remove disabled lenses**: if review configuration specifies210 `disabled_lenses`, remove those from the available set. They are never211 selected regardless of auto-detect criteria.2123. **Mark core lenses**: if review configuration specifies `core_lenses`,213 use that list. Otherwise, the core lenses are Architecture, Code Quality,214 Test Coverage, and Correctness. Core lenses are included unless the change215 is clearly outside their scope.2164. **Auto-detect remaining lenses**: use the criteria below (for built-in217 lenses) and the auto-detect criteria from review configuration (for custom218 lenses) to identify which non-core lenses are relevant to the change.219 Custom lenses that provide auto-detect criteria participate in selection220 like any other non-core lens. Custom lenses without auto-detect criteria221 (marked "always include" in the configuration) are always selected. Custom222 lenses use absolute paths instead of the `${CLAUDE_PLUGIN_ROOT}` lens223 path template.2245. **Apply focus arguments**: if the user provided focus areas, prioritise225 the corresponding lenses and fill remaining slots with auto-detected ones.2266. **Cap at `max_lenses`**: if more lenses than the configured maximum pass227 selection, rank by relevance and drop the least relevant. Prefer lenses228 whose core responsibilities directly overlap with the change's concerns.2297. **Enforce `min_lenses` floor**: never run fewer than `min_lenses` unless230 the change is trivially scoped.231232When presenting the lens selection, clearly indicate which lenses are233selected and which are skipped, with a brief reason for each skip.234235Present lens selection to the user before proceeding:236237```238Based on the PR's scope, I'll review through these lenses:239- Architecture: [reason]240- Security: [reason — or "Skipping: no security-sensitive changes identified"]241- Test Coverage: [reason]242- Code Quality: [reason]243- Standards: [reason — or "Skipping: ..."]244- Usability: [reason — or "Skipping: ..."]245- Performance: [reason — or "Skipping: no performance-sensitive changes identified"]246- Documentation: [reason — or "Skipping: ..."]247- Database: [reason — or "Skipping: no database changes identified"]248- Correctness: [reason]249- Compatibility: [reason — or "Skipping: ..."]250- Portability: [reason — or "Skipping: ..."]251- Safety: [reason — or "Skipping: ..."]252253```254255Then use the `AskUserQuestion` tool to ask the user whether to proceed, with256two options:2572581. **Yes, use the proposed lenses** — run the review with the selected lenses2592. **No, specify which lenses to use** — adjust the selection before running260261Wait for the user's answer before spawning reviewers. If they choose option 2,262ask which lenses they want using a **plain-text question only** — do NOT use263`AskUserQuestion` for this follow-up (the lens list is too large for the2644-option limit). If any lens name is unrecognised, seek clarification. Once265confirmed, update the selection and re-present it using the same266`AskUserQuestion` proceed/adjust pattern. This loop is user-controlled with267no hard termination limit.268269### Step 3: Spawn Review Agents270271For each selected lens, spawn the {reviewer agent} agent with a prompt272that includes paths to the lens skill and output format files. Do NOT read273these files yourself — the agent reads them in its own context.274275**Reminder**: In the template below, replace `{tmp directory}` with the276actual path resolved at the top of this skill before passing the prompt to277the agent.278279Compose each agent's prompt following this template:280281```282You are reviewing pull request changes through the [lens name] lens.283284## Context285286The PR artefacts are in the temp directory at {tmp directory}/pr-review-{number}:287- `diff.patch` — the full diff288- `changed-files.txt` — list of changed file paths289- `pr-description.md` — PR description290- `commits.txt` — commit messages291292PR number: [number]293294## Analysis Strategy2952961. Read your lens skill and output format files (see paths below)2972. Read `diff.patch` and `changed-files.txt` from the temp directory2983. Read `pr-description.md` and `commits.txt` for intent context2994. Explore the codebase to understand the architectural landscape around300 the changes3015. Evaluate the changes through your lens, applying each key question3026. Identify beyond-the-diff impact — trace how changes affect consumers3037. Anchor findings to precise diff line numbers (lines must be within304 diff hunks)305306## Lens307308Read the lens skill at the path listed in the Lens Catalogue table in the309review configuration above. If no review configuration is present, use:310${CLAUDE_PLUGIN_ROOT}/skills/review/lenses/[lens]-lens/SKILL.md311312## Output Format313314Read the output format at: ${CLAUDE_PLUGIN_ROOT}/skills/review/output-formats/pr-review-output-format/SKILL.md315316IMPORTANT: Return your analysis as a single JSON code block. Do not include317prose outside the JSON block.318```319320Spawn all selected agents **in parallel** using the Task tool with321`subagent_type: "!`accelerator config agent reviewer --fail-safe`"`.322323**IMPORTANT**: Wait for ALL review agents to complete before proceeding.324325**Handling malformed agent output**:326327If an agent's response is not a clean JSON block, apply this extraction328strategy:3293301. Look for a JSON code block fenced with triple backticks (optionally with331 a `json` language tag)3322. If found, extract and parse the content within the fences3333. If the extracted JSON is valid, use it normally3344. If no JSON code block is found, or the JSON within it is invalid, apply335 the fallback: treat the agent's entire output as a single general finding336 with the agent's lens name and `"major"` severity, and include it in the337 review summary body338339When falling back, warn the user that the agent's output could not be parsed340and present the raw agent output in a collapsed form so the user can see what341the agent actually found.342343### Step 4: Aggregate and Curate Findings344345Once all reviews are complete:3463471. **Parse agent outputs**: Extract the JSON block from each agent's response348 (see the extraction strategy in Step 3). Collect the `summary`, `strengths`,349 `comments`, and `general_findings` arrays from each.3503512. **Aggregate across agents**:352 - Combine all `comments` arrays into a single list353 - Combine all `general_findings` arrays into a single list354 - Combine all `strengths` arrays into a single list355 - Collect all `summary` strings3563573. **Validate line numbers against the diff**: Parse the hunk headers in358 `diff.patch` to build valid line ranges per file. For each `@@` header:359 - Extract the new-file range from `@@ -a,b +c,d @@` — lines `c` through360 `c+d-1` are valid RIGHT-side lines361 - Extract the old-file range — lines `a` through `a+b-1` are valid362 LEFT-side lines363 - For each comment in the aggregated `comments` list, check that its364 `path`/`line`/`side` falls within a valid range for that file365 - Move any comments with out-of-range lines to `general_findings`366 automatically, preserving all their metadata (severity, lens, title, body)367 - If a comment was moved, note it in the preview so the user knows3683694. **Deduplicate inline comments**: Where multiple agents flag the same file,370 same side, and overlapping or adjacent line range (same path, lines within371 the configured dedup proximity ({dedup proximity}) of each other), consider 372 merging — but only when the findings address the same underlying concern 373 from different lens perspectives. Spatial proximity alone is not sufficient; 374 the findings must be semantically related.375376 When merging:377 - Combine the bodies, attributing each part to its lens378 - Use the highest severity among the merged findings379 - Use the highest confidence among the merged findings380 - Note all contributing lenses in the title381382 When in doubt, keep comments separate — distinct inline comments are easier383 to resolve individually on GitHub than a merged comment covering multiple384 concerns.3853865. **Prioritise and cap inline comments**:387 - Sort by severity: critical > major > minor > suggestion388 - Within the same severity, sort by confidence: high > medium > low389 - Always include all critical findings, even if that exceeds 390 {max inline comments}391 - Select up to the configured max inline comments ({max inline comments}) 392 comments total for inline posting (more if all critical findings push 393 beyond the cap)394 - Move any remaining comments to the summary body as an "Additional395 Findings" list (title + file:line only)3963976. **Determine suggested verdict**:398399 If review configuration provides verdict overrides above, apply those400 thresholds instead of the defaults below:401 - If `pr_request_changes_severity` is `none`, skip this rule (never402 suggest REQUEST_CHANGES based on severity)403 - If any findings at or above the configured `pr_request_changes_severity`404 (default: `critical`) exist → suggest `REQUEST_CHANGES`405 - If only findings below that threshold → suggest `COMMENT`406 - If no findings at all (only strengths) → suggest `APPROVE`4074087. **Identify cross-cutting themes**: Look for findings that appear across409 multiple lenses — issues flagged by 2+ agents reinforce each other and410 should be highlighted in the summary. Also identify tradeoffs where411 different lenses conflict (e.g., security wants more validation, usability412 wants less friction).4134148. **Compose the review summary body** (this becomes the `body` field of the415 GitHub review):416417 ```markdown418 ## Code Review: #{number} - {title}419420 **Verdict:** [APPROVE | REQUEST_CHANGES | COMMENT]421422 [Combined assessment: take each agent's summary and synthesise into 2-3423 sentences covering the overall quality of the PR across all lenses]424425 ### Cross-Cutting Themes426 [Issues that multiple lenses identified — these deserve the most attention]427 - **[Theme]** (flagged by: [lenses]) — [description]428429 ### Tradeoff Analysis430 [Where different lenses disagree, present both perspectives]431 - **[Quality A] vs [Quality B]**: [description and recommendation]432433 [Omit either section if there are no cross-cutting themes or tradeoffs]434435 ### Strengths436 - ✅ [Aggregated and deduplicated strengths from all agents]437438 ### General Findings439 - [emoji] **[Lens]**: [General findings from all agents, sorted by severity]440441 ### Additional Findings442 [Only if more than {max inline comments} inline comments were produced and 443 some were deferred]444 - [emoji] `file:line` — [title] ([lens])445446 ---447 *Review generated by /review-pr*448 ```4494509. **Compose each inline comment body**: Each comment's `body` field should451 already be self-contained from the agent output. For merged comments,452 combine the bodies with a blank line separator and attribute each section453 to its lens.45445510. **Write the review artifact** to `{pr reviews directory}/`:456457 Determine the next review number:458 ```bash459 mkdir -p {pr reviews directory}460 # Glob for existing reviews of this PR461 ls {pr reviews directory}/{number}-review-*.md 2>/dev/null462 # Extract the highest number, increment by 1. If none exist, use 1.463 ```464465 Write the review document to `{pr reviews directory}/{number}-review-{N}.md`.466467#### Populate frontmatter468469The `target:` field is filled automatically from the PR number — this is470what makes the review traceable back to the PR it covers. Per ADR-0034,471the typed-linkage form is `"pr:<pr-number>"`.472473Before writing the PR review file, capture metadata and substitute the474unified base fields and per-type extras into the template's frontmatter475block:4764771. Invoke `accelerator corpus metadata derive`478 to obtain `Current Date/Time (UTC):`.4792. **Substitute** every field below with the indicated value:480 - `type:` ← `pr-review`481 - `id:` ← `{number}-review-{N}` (the review filename stem, where482 `{number}` is the PR number and `{N}` is the next review483 number), always quoted as a YAML string484 - `title:` ← the PR title from `gh pr view --json title`485 - `date:` ← the `Current Date/Time (UTC):` value486 - `author:` ← the author value resolved per `create-work-item/SKILL.md:578-580`487 - `producer:` ← `review-pr`488 - `status:` ← `complete`489 - `last_updated:` ← the same `Current Date/Time (UTC):` value490 - `last_updated_by:` ← the same value resolved for `author`491 - `schema_version:` ← `1` (bare integer, not quoted)492 - `parent:` ← typed-linkage ref to the parent PR (`"pr:NNNN"`).493 Fill when the review names a parent; otherwise omit the key.494 - `target:` ← `"pr:<pr-number>"` (e.g. `"pr:123"`); the495 typed-linkage ref to the PR under review per ADR-0034, must496 match the regex `^"pr:[0-9]+"$`. Always fill — every review has497 a target.498 - `relates_to:` ← list of typed-linkage refs to related reviews or499 artifacts (`["pr-review:NNNN", ...]`). Fill when prior reviews500 are explicit; otherwise omit the key.501 - `reviewer:` ← the reviewer value resolved per `create-work-item/SKILL.md:578-580`502 - `verdict:` ← the verdict from Step 4.6 (`APPROVE | REQUEST_CHANGES | COMMENT`)503 - `lenses:` ← the list of lens names used504 - `review_number:` ← `N` (the next available review number from the505 glob above)506 - `pr_number:` ← the PR number from `gh pr view --json number`507 (bare integer; foreign reference to the external PR per508 ADR-0033 §Identity-value shape contract)509510 The PR title is recorded in the base `title:` field; no separate511 `pr_title:` field is emitted (the unified schema uses the base512 `title:` for all artifact titles per ADR-0033). The `review_pass:`513 field is intentionally absent — `review-pr` has no in-place514 re-review update flow today; re-running it produces a fresh515 `-review-{N+1}.md`.5163. Write the file with the substituted frontmatter block, followed by517 the review summary composed in Step 4.8 and the inline comments518 and per-lens results sections:519520```markdown521{The full review summary from Step 4.8}522523## Inline Comments524525### `{path}:{line}` — {title}526**Severity**: {severity} | **Confidence**: {confidence} | **Lens**: {lens}527528{comment body}529530---531532### `{path}:{line}` — {title}533...534535## Per-Lens Results536537### {Lens 1 Name}538539**Summary**: {agent summary}540541**Strengths**:542{agent strengths}543544**Comments**:545{agent comments — each with path, line, severity, confidence, and body}546547**General Findings**:548{agent general findings}549550### {Lens 2 Name}551552...553```554555This review artifact captures the complete analysis. The GitHub review556(posted in Step 6) may be a curated subset (capped at ~{max inline comments}557inline comments), but the persistent artifact retains everything.558559### Step 5: Present the Review560561Present a two-part preview showing exactly what will be posted to the PR:562563**Part 1: Review summary** (will become the review's body):564565Show the composed summary from Step 4.8 in a markdown code block so the user566can see exactly what will be posted.567568**Part 2: Inline comments** (will be attached to specific diff lines):569570```571## Proposed Inline Comments ([count] comments)572573### [file path 1]574- Line [N]: [emoji] **[Lens]** — [title]575 > [First 1-2 sentences of body as preview]576577- Lines [N-M]: [emoji] **[Lens]** — [title]578 > [First 1-2 sentences of body as preview]579580### [file path 2]581- Line [N]: [emoji] **[Lens]** — [title]582 > [First 1-2 sentences of body as preview]583584[If comments were deferred due to the ~{max inline comments} cap:]585### Deferred to summary ([count] findings)586- [emoji] [Lens]: [title] — `file:line`587```588589### Step 6: Offer Actions590591After presenting the preview:592593```594The review is ready. Would you like to:5951. Post the review? (summary + [count] inline comments, verdict: [suggested verdict])5962. Change the verdict? (currently: [suggested verdict])5973. Edit or remove specific inline comments before posting?5984. Discuss any findings in more detail?5995. Re-run specific lenses with adjusted focus?600```601602**When the user chooses to post** (option 1):6036041. Read the HEAD SHA and repo info from the temp directory at605 `{tmp directory}/pr-review-{number}/head-sha.txt` and606 `{tmp directory}/pr-review-{number}/repo-info.txt` using the Read tool.6076082. Construct the review payload as a JSON object containing:609 - `commit_id`: the HEAD SHA610 - `body`: the review summary composed in Step 4.8611 - `event`: the verdict (`"COMMENT"`, `"REQUEST_CHANGES"`, or `"APPROVE"`)612 - `comments`: array of inline comment objects, each with:613 - `path`: file path from the agent's comment614 - `line`: line number from the agent's comment615 - `side`: side from the agent's comment616 - `body`: the self-contained comment body617 - `start_line` and `start_side`: included only if `end_line` is not null.618 For multi-line comments, the agent's fields map to the API's fields619 with an inversion (see "Multi-Line Comment API Mapping" in Phase 1):620 - API `start_line` ← agent's `line` (the beginning of the range)621 - API `start_side` ← agent's `side`622 - API `line` ← agent's `end_line` (the end of the range)623 - API `side` ← agent's `side`624625 Example: agent `{line: 10, end_line: 15, side: "RIGHT"}` becomes626 API `{start_line: 10, start_side: "RIGHT", line: 15, side: "RIGHT"}`6276283. Write the review payload JSON to629 `{tmp directory}/pr-review-{number}/review-payload.json`, then post the630 review:631 ```bash632 gh api repos/{owner}/{repo}/pulls/{number}/reviews \633 --method POST --input {tmp directory}/pr-review-{number}/review-payload.json634 ```635636 Where `{owner}/{repo}` are the values read from `repo-info.txt`.6376384. Confirm success and show the PR URL:639 ```bash640 gh pr view {number} --json url --jq '.url'641 ```642643**If the API returns a 422 error** (typically an invalid line reference or644stale commit):645- Report the error to the user646- If the error indicates an invalid line reference, identify which comment(s)647 caused the failure and offer to retry without them (move them to the summary)648- If the error indicates a stale `commit_id` (the PR's HEAD has changed since649 the review started), re-fetch the HEAD SHA and warn the user that new commits650 were pushed. Offer to retry with the updated SHA, noting that line numbers651 may have shifted and some comments may now be invalid652653**When the user chooses to edit comments** (option 3):654- Present each comment with a number655- Allow the user to remove specific comments by number656- Allow the user to edit a comment's body text657- After edits, re-present the preview and offer the same action options658659**When the user changes the verdict** (option 2):660- Use the `AskUserQuestion` tool with three options:661 1. **APPROVE** — approve the PR662 2. **COMMENT** — leave a non-blocking comment review663 3. **REQUEST_CHANGES** — request changes before merge664- Update the summary body and re-present the preview665666## Important Guidelines6676681. **Read the diff before doing anything else** — you need complete context to669 select lenses and brief the agents properly6706712. **Spawn agents in parallel** — the review lenses are independent and should672 run concurrently for efficiency6736743. **Synthesise, don't concatenate** — your value is in compiling a balanced675 view across lenses, identifying themes and tradeoffs, and prioritising676 actionable recommendations. Don't just paste seven reports together.6776784. **Be balanced** — highlight strengths alongside concerns. A PR that makes679 good architectural decisions but has security gaps should get credit for680 both.6816825. **Prioritise by impact** — structural issues that are hard to fix later683 matter more than surface-level concerns. A critical finding from one lens684 outweighs minor findings from all seven.6856866. **Respect tradeoffs** — when lenses conflict, present both sides and let the687 user decide. Don't privilege one quality attribute over another without688 justification.6896907. **Clean up temp directory only at session end** — agents may need to691 re-reference the PR context during follow-up discussion.692693 The `{tmp directory}/pr-review-{number}/` directory contains ephemeral694 working data (diff, changed-files, PR description, commits, head SHA,695 repo info, review payload JSON) used during the review session. The review696 itself (summary, inline comments, per-lens results) is persisted separately697 to `{pr reviews directory}/{number}-review-{N}.md`.6986998. **Handle API errors gracefully** — if the review post fails due to invalid700 line references, identify the problematic comments and offer to retry701 without them rather than failing entirely7027039. **Cap inline comments** — if agents produce more findings, prioritise704 critical and major severity. Use the configured max ({max inline comments}).705 Always include all critical findings even if that exceeds the cap. Move 706 overflow to the summary body. This prevents PR comment spam.70770810. **Keep positive feedback in the summary** — strengths and good observations709 go in the review body, never as inline comments. Inline comments are710 exclusively for actionable findings.71171211. **Use emoji severity prefixes consistently** — 🔴 critical, 🟡 major,713 🔵 minor/suggestion, ✅ strengths. **IMPORTANT**: Use the actual Unicode714 emoji characters (🔴 🟡 🔵 ✅), NOT text shortcodes like `:red_circle:`,715 `:yellow_circle:`, `:blue_circle:`, or `:white_check_mark:`. Shortcodes716 are not rendered in markdown and will appear as literal text.717718## What NOT to Do719720- Don't skip writing the review artifact — always persist to721 {pr reviews directory}/ so the full analysis is available to the team722- Don't post inline comments for positive feedback — strengths go in the723 summary only724- Don't post more than the configured max inline comments 725 ({max inline comments}) inline comments — prioritise by severity (always 726 include all critical findings even if that exceeds the cap)727- Don't post generic or vague inline comments — each must be specific and728 actionable729- Don't skip the preview step — always show the user what will be posted730 before posting731- Don't skip the lens selection step — always confirm with the user which732 lenses will run733- Don't present raw agent output — always aggregate and curate into the734 structured format735- Don't run lenses that clearly aren't relevant736- Don't modify any code — this is a read-only review737738## Relationship to Other Commands739740The PR review sits in the development lifecycle alongside other commands:7417421. `/create-plan` — Create the implementation plan7432. `/review-plan` — Review and iterate the plan quality7443. `/implement-plan` — Execute the approved plan7454. `/validate-plan` — Verify implementation matches the plan7465. `/describe-pr` — Generate PR description7476. `/review-pr` — Review the PR through quality lenses (this command)748749!`accelerator config instructions review-pr --fail-safe`