review

name	review
description	Use when reviewing a pull request, branch, commit range, working tree diff, plan, document, or other coherent unit of work across correctness, security, codebase alignment, code quality, test quality, performance, and simplicity.

Review

Overview

Perform seven parallel specialized reviews of a coherent target, then synthesize findings with confidence scoring and severity tiers. Each review dimension runs as an independent reviewer subagent through spawn_agents; results are merged, deduplicated, and presented as one structured report.

Use this skill for review requests targeting a GitHub PR, local branch, commit range, current working tree, plan file, design document, or clearly described unit of work. Preserve the same fundamental approach regardless of target: gather enough context, dispatch independent reviewers, filter low-confidence findings, deduplicate, and report actionable issues plus review gaps.

Input Parsing

Infer the review target from the user's request and local context when possible. Ask one focused clarification question only when the target remains ambiguous after inspection.

Supported target modes:

Mode 1: GitHub PR URL

Matches pattern: https://github.com/<owner>/<repo>/pull/<number>

1. Extract <owner>, <repo>, and <number> from the URL.
2. Use the broker-backed GitHub tools for remote PR data, following the global broker discovery and schema guidance in AGENTS.md.
3. Fetch PR context with name: "github.pull_request_read":
   • method: "get" for title, body, and metadata
   • method: "get_diff" for the unified diff
   • method: "get_files" for changed files and add/delete counts
   • method: "get_comments" for conversation comments
   • method: "get_reviews" for review summaries
   • method: "get_review_comments" for inline review threads/comments
4. If the PR belongs to the current local repository, fetch the PR head without checking it out:
   • Resolve the repo root with local git, compare the local origin URL to <owner>/<repo>, and only use this path when they match.
   • Use the broker-backed git.fetch tool with the absolute repo root, remote origin, and a refspec such as +refs/pull/<number>/head:refs/remotes/origin/pr/<number>.
   • Inspect fetched branch contents locally via git object reads and diffs, such as git diff <default-branch>...refs/remotes/origin/pr/<number> and git show refs/remotes/origin/pr/<number>:<path>.
   • Do not run git checkout, git switch, or otherwise move the working tree to the PR branch.
5. If MCP broker returns a configuration or authentication error, report that remote PR review requires broker access and stop.
6. If the diff is truncated, continue with available context but mark truncation as a review gap in the final report.
7. Do not use the gh CLI for PR URL mode.

Mode 2: Local Branch Name

Use when the input looks like a branch or ref and is not a PR URL.

1. Determine the default branch with local git:

   git symbolic-ref --short refs/remotes/origin/HEAD
   

   Fall back to origin/main, then main, if the command fails.
2. Fetch the diff with merge-base semantics:

   git diff <default-branch>...<branch>
   

3. Fetch changed file names:

   git diff --name-only <default-branch>...<branch>
   

4. No PR metadata is available in this mode unless the user provides it.

Mode 3: Commit Range or Ref Expression

Use when the input contains a commit range or explicit git refs, such as abc123..def456, main...HEAD, or HEAD~3.

1. Resolve the refs locally with git where possible.
2. Fetch the diff and changed file names with the user's range semantics unless obviously invalid.
3. If the expression is invalid or ambiguous, ask one focused clarification question.

Mode 4: Current Working Tree

Use when the user asks to review local changes, unstaged changes, staged changes, the current branch without naming it, or provides no target while the working tree has changes.

1. Inspect git status --short.
2. Gather staged and unstaged diffs:

   git diff --cached
   git diff
   

3. Include untracked file contents when they appear relevant and are safe to read.
4. If there are no local changes and no other target is inferable, ask what to review.

Mode 5: Plan or Document

Use when the target is a plan file, design doc, ticket, markdown document, or other non-code artifact.

1. Read the target document and any linked local files needed to understand it.
2. Gather relevant repository context and guidance, but do not invent a code diff.
3. Frame reviewer prompts around risks in the proposed work, missing requirements, security implications, test strategy, performance implications, and alignment with codebase conventions.
4. Record the absence of an implementation diff as a review gap when judging code-level correctness.

Mode 6: Described Unit of Work

Use when the user describes work to review without a concrete PR, branch, range, diff, or file.

1. Inspect local context for likely artifacts: current branch, dirty tree, .plans/, recent commits, and mentioned files.
2. If a single target is strongly implied, review it and state the assumption.
3. If multiple plausible targets remain, ask one focused clarification question.

Gather Context

After obtaining target material:

1. Parse changed files from the PR file list, git diff --name-only, diff headers (+++ b/ and --- a/), or document references.
2. Read full local file contents for changed files when the workspace appears to be a checkout of the reviewed code. In PR URL mode for the current repository, prefer contents from the fetched PR ref rather than the working tree. If a file is missing or local content may not match the reviewed target, rely on the diff and record the limitation.
3. Read relevant project guidance files when present, especially AGENTS.md, CLAUDE.md, and nearby repository docs that define review or code conventions.
4. In PR URL mode, include PR title, description, conversation comments, review summaries, and inline review comments.
5. For plans or documents, include the artifact text, nearby referenced files, acceptance criteria, and explicit assumptions.
6. Assemble a context package for reviewers with:
   • review target and input mode
   • target metadata if available
   • prior comments/reviews if available
   • changed file list or referenced artifacts
   • unified diff when available
   • relevant full-file context where available
   • project guidance files
   • explicit gaps such as truncated diff, missing file context, unavailable PR comments, no implementation diff, or ambiguous target assumptions

Dispatch Reviewers

Before launching LLM reviewers, run deterministic checks that are practical for the target, such as typecheck, lint, tests, format checks, or focused validation scripts. Include passing results, failures, unavailable checks, and any skipped-check rationale in the context package. Do not pretend failed or unavailable deterministic checks passed; reviewers should receive the real pass-or-report state.

Read each prompt file from references/ at dispatch time, then launch all seven reviewers in one spawn_agents call. Use the reviewer agent type for every reviewer. Each agent prompt is the relevant prompt file content plus the full context package.

#	Reviewer	Prompt File	Intent example
1	Correctness	references/correctness-prompt.md	correctness review
2	Security	references/security-prompt.md	security review
3	Codebase Fit	references/codebase-fit-prompt.md	codebase fit
4	Code Quality	references/code-quality-prompt.md	code quality
5	Test Quality	references/test-quality-prompt.md	test quality
6	Performance	references/performance-prompt.md	performance review
7	Simplicity	references/simplicity-prompt.md	simplicity review

The reviewer agent definition owns the shared scope, evidence, confidence, severity, and machine-readable output contract. Lens prompts should contain only their specialized rubric. Expect either FINDINGS: lines in the reviewer's documented format or NO_FINDINGS.

Synthesize

After all seven agents return:

1. Parse each response for FINDINGS: or NO_FINDINGS.
2. Treat malformed reviewer output conservatively: parse any usable finding lines, count the malformed response as a review gap, and do not invent missing findings.
3. Filter out any finding with confidence below 80.
4. Deduplicate findings that point to the same file and line range within 3 lines or describe the same root cause. Merge duplicates by keeping the highest severity and confidence, then note all contributing reviewers.
5. Group by severity: Blockers > Important > Suggestions.
6. Determine verdict:
   • Ready to Merge — 0 blockers, 0 important, and an implementation-oriented target was reviewed
   • Looks Sound — 0 blockers, 0 important, and a non-merge target such as a plan or document was reviewed
   • Needs Attention — 0 blockers, 1+ important
   • Needs Work — 1+ blockers
7. Surface review gaps such as truncated diff, missing file context, unavailable PR comments, no implementation diff, ambiguous target assumptions, or malformed reviewer output.

Output Format

Present results using this template. Omit empty severity sections.

## Review: <target title, branch, range, file, or description>

**Verdict: <verdict>** (<N> blockers, <N> important, <N> suggestions)

---

### Blockers

**[<Category>] <Title>** (confidence: <N>)
`<file>:<line>` — <Reviewer(s)>
<Description>

### Important

**[<Category>] <Title>** (confidence: <N>)
`<file>:<line>` — <Reviewer(s)>
<Description>

### Suggestions

**[<Category>] <Title>** (confidence: <N>)
`<file>:<line>` — <Reviewer(s)>
<Description>

---

<N> agents reviewed <N> files/artifacts. <N> raw findings → <N> surfaced (80+ confidence).

Review gaps: <none or concise list>

Pi Notes

• reviewer subagents use the model and thinking level configured in pi/agent/agents/reviewer.md.
• Remote PR review depends on the mcp-broker extension and authenticated GitHub broker tools. For PRs in the current repository, use authenticated git.fetch through the broker to fetch the PR ref for local inspection without checking it out.
• Large PR diffs may be truncated by github.pull_request_read with method: "get_diff"; use changed-file summaries, available full-file context, and review-gap reporting rather than pretending the review is complete.
• spawn_agents reviewers start with fresh context and read-only tools, so brief them with all relevant context and constraints.