Code Review

Multi-Agent Code Review

Pragmatic Quality framework — orchestrate parallel review agents for high-signal findings.

Parse Arguments

• If $ARGUMENTS contains --post-to-pr: enable GitHub PR posting (Phase 5)
• Remaining non-flag arguments: use as output directory (default: ./reviews/code/)

Example usage:

• /review:code-review — local report to ./reviews/code/
• /review:code-review custom/dir — local report to custom/dir/
• /review:code-review --post-to-pr — local report + post to GitHub PR
• /review:code-review custom/dir --post-to-pr — both

Git Analysis

Analyze these outputs to understand the scope and content of the changes.

GIT STATUS:

!`git status`

FILES MODIFIED:

!`git diff --name-only origin/HEAD...`

COMMITS:

!`git log --no-decorate origin/HEAD...`

DIFF CONTENT:

!`git diff --merge-base origin/HEAD`

Phase 1 — Context Gathering

Launch 2 parallel Haiku agents:

Agent A — CLAUDE.md Discovery: Find all CLAUDE.md files in the repo (root + directories modified by the changes). Return file paths and brief content summaries of each.

Agent B — Change Summary: Analyze the diff above. Return: files changed count, primary areas affected, change type (feature/bugfix/refactor/config/test/docs), estimated risk level (Low/Medium/High/Critical).

Phase 2 — Parallel Review

Launch 4-5 Sonnet agents simultaneously. Provide each with: the full diff content, the CLAUDE.md summaries from Phase 1, and the change summary. Each agent returns findings in this format:

Finding: {description}
File: {path}:{line}
Category: {CLAUDE.md | Bug | History | Security | Comments}
Reason: {why this was flagged}
Suggested fix: {code snippet, if applicable}

Reviewer 1 — CLAUDE.md Compliance

Audit changes against all discovered CLAUDE.md rules. Only flag items specifically called out in a CLAUDE.md. Double-check that the CLAUDE.md actually requires what is being flagged. Ignore silenced rules (lint-ignore comments).

Reviewer 2 — Bug Scanner

Shallow scan for obvious bugs in the diff only. Focus on large bugs — avoid nitpicks. Do NOT read extra context beyond the changes. Ignore issues linters/typecheckers would catch.

Reviewer 3 — Git Blame/History Analyzer

Read git blame and history of modified files. Identify issues in light of historical context: reverted changes being re-modified, recently-fixed areas, breaking established conventions, patterns from previous PR comments.

Reviewer 4 — Security Reviewer

Security-focused scan: injection (SQLi, XSS, command), auth/access control, secrets/credentials, data exposure in logs/responses, crypto misuse. Only report HIGH confidence exploitable findings.

Reviewer 5 — Code Comments Compliance (conditional)

Only launch if modified files contain substantive code comments (// NOTE:, // IMPORTANT:, // INVARIANT:, // SAFETY:, // TODO:). Ensure changes comply with guidance in those comments.

False Positive Awareness

All reviewers must skip these false positive categories:

• Pre-existing issues not introduced in the changes
• Issues that linters, typecheckers, or compilers would catch
• Pedantic nitpicks a senior engineer wouldn't flag
• Framework-handled concerns (e.g., XSS in React unless using unsafe HTML injection APIs)
• General quality issues unless explicitly required in CLAUDE.md
• Style preferences matching existing codebase conventions
• Real issues on lines the author did not modify

See WORKFLOW.md for detailed false positive filtering rules.

Phase 3 — Confidence Scoring

For each finding from Phase 2, launch a parallel Haiku agent that:

1. Receives: the finding description, the relevant diff section, and the CLAUDE.md files list 2. Scores 0-100 using this rubric:

• 0: False positive — doesn't hold up to scrutiny, or pre-existing issue
• 25: Might be real, but may also be false positive. Unable to verify.
• 50: Verified issue, but minor or nitpick. Not very important relative to the rest.
• 75: Very likely real. Existing approach is insufficient. Important and impactful.
• 100: Confirmed. Will happen in practice. Evidence directly confirms this.

3. For CLAUDE.md findings: double-check the CLAUDE.md actually calls out the issue 4. Returns: score + brief justification

Filter: Remove all findings scoring below 80. If no findings survive, generate a clean report.

Phase 4 — Report Generation

Generate the report using the template in WORKFLOW.md.

Map confidence scores to triage levels:

• 90-100 → Blocker (if severity warrants) or Improvement
• 80-89 → Improvement or Question

Include for each finding: the Source category (CLAUDE.md, Bug Scan, Git History, Security, Comments).

1. Create output directory: mkdir -p {output-directory} 2. Save report to: {output-directory}/{YYYY-MM-DD}_{HH-MM-SS}_code-review.md 3. Display the full report to the user 4. Confirm the save path

Phase 5 — Optional GitHub PR Posting

Only execute if --post-to-pr flag was passed.

1. Check if an open PR exists for the current branch via gh pr view 2. If no PR exists, inform the user: "No open PR found for this branch. Skipping GitHub posting." 3. If a PR exists, check eligibility via a Haiku agent:

• Is the PR closed? → skip
• Is the PR a draft? → skip
• Has Claude already commented on this PR? → skip

4. If eligible, format findings as a concise PR comment and post via gh pr comment 5. Use the GitHub comment format from WORKFLOW.md

Phase 6 — Automatic Verification

After saving the report, invoke the false-positive verifier:

1. Use the Skill tool to invoke review:verify-findings with the saved report path 2. The verifier runs in an isolated forked context and produces a .verified.md report 3. After verification completes, inform the user of both report locations

If the Skill tool is not available (e.g., running inside a subagent):

Run verification manually: /review:verify-findings {report-path}

Resources

• WORKFLOW.md — Detailed review checklists, agent prompt templates, scoring rubric, report template, GitHub comment format
• EXAMPLES.md — Sample reports and orchestration flow examples
• TROUBLESHOOTING.md — Common issues with pipeline, scoring, and output

Code Review Examples

Invocation

# Default output path
/review:code-review

# Custom output path
/review:code-review custom/reviews/

# With GitHub PR posting
/review:code-review --post-to-pr

# Custom path + PR posting
/review:code-review custom/reviews/ --post-to-pr

Orchestration Flow

What the user sees during a typical multi-agent review:

/review:code-review

Phase 1: Gathering context...
  - Agent A: Found 2 CLAUDE.md files (root, src/)
  - Agent B: 8 files changed | Feature | Medium risk

Phase 2: Running 5 parallel reviewers...
  - CLAUDE.md compliance: 1 finding
  - Bug scanner: 2 findings
  - Git history: 0 findings
  - Security: 1 finding
  - Code comments: skipped (no substantive comments)

Phase 3: Scoring 4 findings...
  - Finding 1 (CLAUDE.md): 85/100 — kept
  - Finding 2 (Bug): 92/100 — kept
  - Finding 3 (Bug): 45/100 — filtered
  - Finding 4 (Security): 88/100 — kept

Phase 4: Generating report... 3 findings (1 Blocker, 2 Improvements)
Report saved to: ./reviews/code/2026-03-18_14-30-00_code-review.md

Phase 6: Running verification...
Verified report saved to: ./reviews/code/2026-03-18_14-30-00_code-review.verified.md

Orchestration Flow — Non-PR Branch

When reviewing changes on a branch without a PR:

/review:code-review

Phase 1: Gathering context...
  - Agent A: Found 1 CLAUDE.md file (root)
  - Agent B: 3 files changed | Bugfix | Low risk

Phase 2: Running 4 parallel reviewers...
  - CLAUDE.md compliance: 0 findings
  - Bug scanner: 0 findings
  - Git history: 0 findings
  - Security: 0 findings

Phase 3: No findings to score.

Phase 4: Generating clean report...
Report saved to: ./reviews/code/2026-03-18_10-15-00_code-review.md

Phase 6: Running verification...
Verified report saved to: ./reviews/code/2026-03-18_10-15-00_code-review.verified.md

Orchestration Flow — With PR Posting

/review:code-review --post-to-pr

Phase 1: Gathering context...
  ...

Phase 2-4: (same as above)
Report saved to: ./reviews/code/2026-03-18_16-00-00_code-review.md

Phase 5: Posting to GitHub PR...
  - PR #42 on feat/auth-refactor — open, eligible
  - Posted review comment with 3 findings

Phase 6: Running verification...

Orchestration Flow — PR Posting Skipped

/review:code-review --post-to-pr

Phase 1-4: (same as above)
Report saved to: ./reviews/code/2026-03-18_16-00-00_code-review.md

Phase 5: No open PR found for this branch. Skipping GitHub posting.

Phase 6: Running verification...

Sample Report — Mixed Findings

# Pragmatic Code Review Report

**Date**: 2025-06-15T14:30:00Z
**Branch**: feat/user-authentication
**Commit**: a1b2c3d
**Reviewer**: Claude Code (multi-agent code review)
**Review Mode**: Multi-Agent Orchestration (4 reviewers, confidence threshold: 80)

## PR Assessment

| Attribute | Value |
|-----------|-------|
| **Risk Level** | High |
| **Change Type** | Feature |
| **Atomicity** | Atomic |
| **Breaking Changes** | None |

---

## Summary

This PR adds JWT-based user authentication with login/signup endpoints. The overall approach is sound and follows existing patterns well. However, there is a critical security issue with token validation and a SQL injection vulnerability that must be addressed before merge. Two improvements would strengthen error handling and logging.

## Findings

### Blockers

- **[Blocker]** `src/auth/middleware.ts:45` — JWT secret read from `process.env.JWT_SECRET` without startup validation. If the env var is missing, `jwt.verify()` receives `undefined` and silently accepts any token. (Confidence: 95/100, Source: Security)
  - **Principle**: Defense in depth — fail securely when configuration is missing
  - **Current**:

const secret = process.env.JWT_SECRET; const decoded = jwt.verify(token, secret);

  - **Suggested**:

const secret = process.env.JWT_SECRET; if (!secret) throw new Error('JWT_SECRET is required'); const decoded = jwt.verify(token, secret);

- **[Blocker]** `src/auth/repository.ts:15` — SQL injection via string interpolation in user lookup query. (Confidence: 98/100, Source: Security)
  - **Principle**: OWASP A03 Injection — never construct queries from user input
  - **Current**:

const result = await db.query(SELECT * FROM users WHERE email = '${email}');

  - **Suggested**:

const result = await db.query('SELECT * FROM users WHERE email = $1', [email]);

### Improvements

- **[Improvement]** `src/auth/controller.ts:28` — Password logged in error handler at debug level. Even at debug level, this creates risk if debug logging is enabled in production. (Confidence: 88/100, Source: Bug Scan)
  - **Principle**: Data minimization — never log credentials regardless of log level
  - **Current**:

logger.debug('Login attempt', { email, password });

  - **Suggested**:

logger.debug('Login attempt', { email, timestamp: Date.now() });

### Questions

- **[Question]** `src/auth/middleware.ts:62` — The token expiry is set to 7 days. Is this intentional for this app's security requirements, or should it be shorter (e.g., 1 hour with refresh tokens)? (Source: Security)

### Praise

- **[Praise]** `src/auth/service.ts:10-35` — Clean separation of auth logic into a dedicated service layer with proper dependency injection. This makes the auth flow testable and follows the existing service pattern well.

### Nitpicks

- **[Nit]** `src/auth/types.ts:8` — `TokenPayload` interface uses `any` for the `metadata` field. Consider `Record<string, unknown>` for type safety.

## Verdict

- **Recommendation**: Request Changes
- **Risk Level**: High
- **Blockers**: 2
- **Improvements**: 1
- **Questions**: 1
- **Nits**: 1

Sample Report — Clean Review

# Pragmatic Code Review Report

**Date**: 2025-06-20T10:15:00Z
**Branch**: fix/pagination-offset
**Commit**: d4e5f6g
**Reviewer**: Claude Code (multi-agent code review)
**Review Mode**: Multi-Agent Orchestration (4 reviewers, confidence threshold: 80)

## PR Assessment

| Attribute | Value |
|-----------|-------|
| **Risk Level** | Low |
| **Change Type** | Bugfix |
| **Atomicity** | Atomic |
| **Breaking Changes** | None |

---

## Summary

This PR fixes an off-by-one error in the pagination logic that caused the last item on each page to be duplicated on the next page. The fix is minimal, correct, and includes a regression test. Clean implementation.

## Findings

### Blockers

None.

### Improvements

None.

### Questions

None.

### Praise

- **[Praise]** `tests/pagination.test.ts:38-55` — Excellent regression test that specifically targets the page boundary duplication bug with clear assertion messages. This prevents future regressions on the exact scenario.

### Nitpicks

- **[Nit]** `tests/pagination.test.ts:42` — Test name "should work correctly" could be more descriptive. Consider "should not duplicate items across page boundaries".

## Verdict

- **Recommendation**: Approve
- **Risk Level**: Low
- **Blockers**: 0
- **Improvements**: 0
- **Questions**: 0
- **Nits**: 1

Sample GitHub PR Comment

When using --post-to-pr, the posted comment looks like:

### Code review

Found 3 issues:

1. JWT secret read without validation — if env var is missing, jwt.verify() silently accepts any token (Security: defense-in-depth violation)

https://github.com/owner/repo/blob/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0/src/auth/middleware.ts#L44-L48

2. SQL injection via string interpolation in user lookup query (Security: OWASP A03 Injection)

https://github.com/owner/repo/blob/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0/src/auth/repository.ts#L14-L16

3. Password logged in debug error handler (Bug Scan: data minimization violation)

https://github.com/owner/repo/blob/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0/src/auth/controller.ts#L27-L29

---

Generated with [Claude Code](https://claude.ai/code)

<sub>If this review was useful, react with :+1:. Otherwise, react with :-1:.</sub>

Code Review Troubleshooting

Common issues when using the code-review skill.

---

Git Diff Issues

"No diff output" or empty diff

Cause: No remote tracking branch, or origin/HEAD is not set.

Fix:

# Set origin/HEAD to the default branch
git remote set-head origin --auto

# Or specify the base branch explicitly
git diff --merge-base origin/main

Diff is too large — review times out or context is truncated

Cause: PR contains too many changed files (generated code, lock files, large migrations).

Fix:

• Split large PRs into smaller, focused changes
• Exclude generated files: git diff --merge-base origin/HEAD -- ':!package-lock.json' ':!*.generated.ts'
• Review high-risk files individually rather than the full diff

---

Multi-Agent Pipeline Issues

A reviewer agent fails or times out

Symptoms: Report notes "Note: {reviewer-name} did not complete. Partial review."

Fix: This is expected behavior — the pipeline continues with results from successful agents. If a specific reviewer consistently fails:

• Check if the diff is too large for that reviewer's scope
• The Git History reviewer (Reviewer 3) may time out on files with extensive blame history
• Rerun the review to retry

All reviewer agents fail

Symptoms: Report uses single-agent fallback mode instead of multi-agent.

Fix: This typically indicates a systemic issue:

• Check network connectivity (agents need to spawn)
• Verify the diff content is valid and non-empty
• The fallback produces a valid review using the same methodology

Reviewer 5 (Code Comments) never runs

Symptoms: Only 4 reviewers launch instead of 5.

Fix: This is intentional. Reviewer 5 only launches when modified files contain substantive code comments (// NOTE:, // IMPORTANT:, // INVARIANT:, // SAFETY:, // TODO:). If no such comments exist, it's skipped to save resources.

---

Confidence Scoring Issues

All findings filtered out (score < 80)

Symptoms: Clean report on a branch with significant changes.

Fix: This means all reviewer findings were scored below the confidence threshold. This is expected for:

• Clean, well-written code
• Changes that follow established patterns
• Minor refactors with no behavioral changes

If you believe issues were missed, check the reviewer outputs before scoring was applied.

Scoring seems inconsistent

Symptoms: Similar issues scored very differently.

Fix: Each finding is scored by an independent Haiku agent. Slight variation is expected. The 80 threshold is calibrated to filter speculative findings while keeping real issues. If a finding was incorrectly filtered, run the review again — scoring agents may produce slightly different results.

Too many findings survive filtering

Symptoms: Report has 8+ findings after scoring.

Fix: If many findings score 80+, it indicates genuine issues in the code. The pipeline does not impose an arbitrary cap — all high-confidence findings are reported. Address the highest-confidence ones first. If the report feels overwhelming, focus on Blockers before Improvements.

Scoring agent fails for a finding

Symptoms: A finding appears in the report without a confidence score justification, or the report notes a scoring agent failure.

Fix: When a scoring agent fails, the finding defaults to a score of 80 (at threshold) and stays in the report. This is the expected safe behavior — it prevents real issues from being silently dropped. If the finding is a false positive, run /review:verify-findings on the report for additional verification.

---

GitHub PR Posting Issues

"No open PR found" when PR exists

Cause: gh pr view can't find the PR for the current branch.

Fix:

# Verify gh CLI is authenticated
gh auth status

# Check if PR exists for this branch
gh pr list --head $(git branch --show-current)

# If branch isn't pushed, push first
git push -u origin $(git branch --show-current)

PR comment fails to post

Cause: Permission denied or PR state changed during review.

Fix:

• Verify gh auth status shows correct permissions
• Check if the PR was closed/merged during the review
• Ensure you have write access to the repository

PR posting skipped — "already reviewed"

Cause: The eligibility check detected a previous Claude Code review comment on the PR.

Fix: This prevents duplicate reviews. If you want to re-review:

• Delete the previous review comment on the PR
• Run /review:code-review --post-to-pr again

---

Finding Quality Issues

Too many findings (noisy report)

Symptoms: Report has many low-signal or speculative findings.

Fix:

• The pipeline enforces a confidence threshold of 80/100 — findings below this are filtered
• If noise persists, run /review:verify-findings on the report for additional false positive verification
• Check that the diff doesn't include generated files or lock files

Too few findings (suspiciously clean)

Symptoms: Clean report on a branch with significant new functionality.

Fix:

• Verify the diff output contains all changed files
• Check that origin/HEAD points to the correct base branch
• Review manually for missed categories (security, performance, testing)

False positives in report

Symptoms: Findings flag patterns that are established conventions or framework-handled concerns.

Fix:

• Run /review:verify-findings {report-path} for automatic false positive verification
• The verifier traces code paths and checks framework protections
• Phase 3 scoring should catch most false positives — if it didn't, the finding may warrant closer inspection

---

Output Issues

Report directory creation fails

Cause: Permission denied or invalid path.

Fix: Ensure the output directory path is writable. Default is ./reviews/code/ relative to the project root.

Report file already exists

The skill uses timestamped filenames ({YYYY-MM-DD}_{HH-MM-SS}_code-review.md), so collisions are rare. If running multiple reviews in the same second, the second review overwrites the first.

Code Review Workflow

Detailed review checklists, agent prompt templates, scoring rubric, report template, and GitHub comment format.

---

Multi-Agent Pipeline Details

Agent Prompt Templates

Each Phase 2 reviewer agent receives this shared context preamble:

You are reviewing code changes. Here is your context:

CLAUDE.md FILES:
{claude_md_summaries from Phase 1 Agent A}

CHANGE SUMMARY:
{summary from Phase 1 Agent B}

DIFF CONTENT:
{full diff}

FALSE POSITIVES TO SKIP:
- Pre-existing issues not introduced in the changes
- Issues that linters, typecheckers, or compilers would catch
- Pedantic nitpicks a senior engineer wouldn't flag
- Framework-handled concerns
- General quality issues unless explicitly required in CLAUDE.md
- Style preferences matching existing codebase conventions
- Real issues on lines the author did not modify
- Something that looks like a bug but is not actually a bug
- Changes in functionality that are likely intentional
- Issues explicitly silenced in code (lint-ignore comments)

Return findings in this format (one per finding):

Finding: {description}
File: {path}:{line}
Category: {your category}
Reason: {why this was flagged, cite evidence}
Suggested fix: {code snippet, if applicable}

If no issues found, return: "No issues found."

Reviewer 1 — CLAUDE.md Compliance

Your role: Audit code changes for compliance with the project's CLAUDE.md guidelines.

Rules:
- Only flag items SPECIFICALLY called out in a CLAUDE.md file
- Double-check that the CLAUDE.md actually requires what you are flagging
- CLAUDE.md is guidance for Claude as it writes code — not all instructions are applicable during code review
- If an issue is silenced in code (lint-ignore comment), do not flag it
- Use Category: CLAUDE.md

Focus on: naming conventions, architecture patterns, forbidden patterns, required practices, testing requirements, and any explicit "NEVER" or "ALWAYS" rules in the CLAUDE.md files.

Reviewer 2 — Bug Scanner

Your role: Shallow scan for obvious bugs in the code changes ONLY.

Rules:
- Focus on LARGE bugs — ignore small issues and nitpicks
- Only look at the diff content — do NOT read extra context beyond the changes
- Ignore issues that a linter, typechecker, or compiler would catch (missing imports, type errors, formatting)
- Ignore pre-existing issues on unchanged lines
- Use Category: Bug

Focus on: null/undefined errors, off-by-one errors, logic inversions, missing error handling on critical paths, incorrect API usage, broken control flow, data loss scenarios.

Reviewer 3 — Git Blame/History Analyzer

Your role: Analyze git blame and history of modified files to identify issues in historical context.

Rules:
- Read git blame for each modified file to understand the history
- Read recent commits touching these files for context
- Use Category: History

Focus on: reverted changes being re-introduced, recently-fixed bugs in the same area, breaking patterns established by previous authors, ignoring guidance from previous PR comments, modifying areas that were specifically stabilized.

Commands to use:
- git blame {file} — for each modified file
- git log --oneline -10 -- {file} — recent history per file
- git log --all --oneline --grep="fix" -- {file} — find previous fixes

Reviewer 4 — Security Reviewer

Your role: Security-focused scan of code changes.

Rules:
- Only report HIGH confidence exploitable findings
- Do not flag theoretical or speculative security issues
- Use Category: Security

Focus on:
- Input validation: SQL injection, XSS, command injection, path traversal
- Authentication/authorization: bypasses, missing checks, privilege escalation
- Secrets: hardcoded API keys, tokens, passwords, credentials in code
- Data exposure: PII in logs, verbose error messages, sensitive data in responses
- Cryptographic issues: weak algorithms, improper key management
- SSRF, open redirects, insecure deserialization

Reviewer 5 — Code Comments Compliance (conditional)

Your role: Ensure code changes comply with guidance in code comments.

Rules:
- Only launch if modified files contain substantive comments: // NOTE:, // IMPORTANT:, // INVARIANT:, // SAFETY:, // TODO:, // HACK:, // WARNING:
- Check that changes respect the intent documented in those comments
- Use Category: Comments

Focus on: violated invariants, ignored safety notes, broken assumptions documented in comments, TODO items that are now relevant to the change.

Agent Output Format

Each reviewer returns structured findings. Example:

Finding: JWT secret read from environment without validation — if missing, jwt.verify() silently accepts any token
File: src/auth/middleware.ts:45
Category: Security
Reason: process.env.JWT_SECRET used directly without null check. jwt.verify(token, undefined) is a known bypass.
Suggested fix:
const secret = process.env.JWT_SECRET;
if (!secret) throw new Error('JWT_SECRET environment variable is required');
const decoded = jwt.verify(token, secret);

Phase Transition Logic

• Phase 1 → Phase 2: Wait for both Haiku agents to complete. If Agent A finds no CLAUDE.md files, skip Reviewer 1 (CLAUDE.md compliance). If Agent B indicates Low risk + test-only/docs-only change, consider running fewer reviewers.
• Phase 2 → Phase 3: Collect all findings from all reviewers. Deduplicate: if two reviewers flag the same file:line, keep the more detailed finding. If no findings from any reviewer, skip Phase 3 and generate a clean report.
• Phase 3 → Phase 4: Filter findings below 80. If all filtered, generate clean report.
• Phase 4 → Phase 5: Report always generated. Phase 5 only runs if --post-to-pr flag was set.
• Phase 5 → Phase 6: Phase 6 always runs (unless Skill tool unavailable).

Error Handling

• If a reviewer agent fails (timeout, error): continue with results from successful agents. Add note to report: "Note: {reviewer-name} did not complete. Partial review."
• If ALL reviewers fail: fall back to single-agent review — analyze the diff directly using the Hierarchical Review Framework below.
• If a scoring agent fails for a finding: default that finding's score to 80 (conservative — finding stays in the report). Better to surface a potential false positive than silently drop a real issue.

---

Hierarchical Review Framework

Reference material for review agents and single-agent fallback.

1. Architectural Design & Integrity (Critical)

• Evaluate if the design aligns with existing architectural patterns and system boundaries
• Assess modularity and adherence to Single Responsibility Principle
• Identify unnecessary complexity — could a simpler solution achieve the same goal?
• Verify the change is atomic (single, cohesive purpose) not bundling unrelated changes
• Check for appropriate abstraction levels and separation of concerns

2. Functionality & Correctness (Critical)

• Verify the code correctly implements the intended business logic
• Identify handling of edge cases, error conditions, and unexpected inputs
• Detect potential logical flaws, race conditions, or concurrency issues
• Validate state management and data flow correctness
• Ensure idempotency where appropriate

3. Security (Non-Negotiable)

• Verify all user input is validated, sanitized, and escaped (XSS, SQLi, command injection prevention)
• Confirm authentication and authorization checks on all protected resources
• Check for hardcoded secrets, API keys, or credentials
• Assess data exposure in logs, error messages, or API responses
• Validate CORS, CSP, and other security headers where applicable
• Review cryptographic implementations for standard library usage

4. Maintainability & Readability (High Priority)

• Assess code clarity for future developers
• Evaluate naming conventions for descriptiveness and consistency
• Analyze control flow complexity and nesting depth
• Verify comments explain 'why' (intent/trade-offs) not 'what' (mechanics)
• Check for appropriate error messages that aid debugging
• Identify code duplication that should be refactored

5. Testing Strategy & Robustness (High Priority)

• Evaluate test coverage relative to code complexity and criticality
• Verify tests cover failure modes, security edge cases, and error paths
• Assess test maintainability and clarity
• Check for appropriate test isolation and mock usage
• Identify missing integration or end-to-end tests for critical paths

6. Performance & Scalability (Important)

• Backend: Identify N+1 queries, missing indexes, inefficient algorithms
• Frontend: Assess bundle size impact, rendering performance, Core Web Vitals
• API Design: Evaluate consistency, backwards compatibility, pagination strategy
• Review caching strategies and cache invalidation logic
• Identify potential memory leaks or resource exhaustion

7. Dependencies & Documentation (Important)

• Question necessity of new third-party dependencies
• Assess dependency security, maintenance status, and license compatibility
• Verify API documentation updates for contract changes
• Check for updated configuration or deployment documentation

---

Diff-Context Awareness

Go beyond the diff to detect cross-file impacts:

Context Probes

When to Ask Questions vs. Assert

• If context outside the diff could justify the change, use [Question] not [Blocker]
• Example: "Is this timeout intentionally set to 0, or should it use the default?"
• Only assert a finding as Blocker when you can verify the issue from the diff + context probes

---

False Positive Filtering

Apply these rules before finalizing findings. Discard any finding that matches a hard exclusion.

Hard Exclusions

1. Style-only issues — defer to linters (formatting, import order, trailing whitespace) 2. Theoretical performance — do not flag without measurable impact or Big-O degradation 3. Subjective preferences — discard if you cannot cite a named engineering principle 4. Test-only file issues — do not flag patterns in test files that don't affect production code 5. Framework-handled concerns — do not flag concerns handled by the framework's security model 6. Missing features not in scope — do not flag features the changes didn't intend to add 7. Consistent naming — do not nitpick naming that matches the existing codebase convention 8. Established patterns — do not flag code patterns used elsewhere in the codebase as issues 9. Code outside the diff — do not report on unchanged code unless directly impacted by the change 10. Vague suggestions — discard any finding that says "could be improved" without specific impact

Signal Quality Criteria

For each remaining finding, verify: 1. Is there a concrete, demonstrable impact (bug, security risk, performance degradation, maintenance burden)? 2. Can you name the engineering principle being violated? 3. Is the suggestion actionable with a specific fix (not just "consider improving")? 4. Would a senior engineer confidently raise this in a PR review?

If any answer is "no," suppress the finding.

---

Confidence Scoring (0-100 Scale)

Scoring Rubric

Threshold & Triage Mapping

Deduplication

If two reviewers flag the same issue (same file:line or overlapping concern):

• Keep the higher-confidence version
• Merge context from both if complementary
• Do not report the same issue twice

---

Communication Principles

Actionable Feedback

Provide specific, actionable suggestions. Include file path and line number for every finding.

Before/After Code Blocks

Blocker and Improvement findings must include code showing current state and suggested fix:

Current (`file:line`):
  code here

Suggested:
  improved code here

Explain the "Why"

When suggesting changes, explain the underlying engineering principle:

• Security: OWASP Top 10, defense-in-depth, least privilege
• Design: Specific SOLID principle, DRY, KISS, YAGNI
• Performance: Big-O impact, specific metric or query pattern
• Testing: Test pyramid, test isolation, coverage strategy

Constructive Tone

Maintain objectivity and assume good intent. The goal is net improvement, not perfection.

---

Report Template

# Pragmatic Code Review Report

**Date**: {ISO 8601 date}
**Branch**: {current branch name}
**Commit**: {short commit hash}
**Reviewer**: Claude Code (multi-agent code review)
**Review Mode**: Multi-Agent Orchestration ({N} reviewers, confidence threshold: 80)

## PR Assessment

| Attribute | Value |
|-----------|-------|
| **Risk Level** | {Low / Medium / High / Critical} |
| **Change Type** | {Feature / Bugfix / Refactor / Config / Test-only / Docs} |
| **Atomicity** | {Atomic / Mixed — consider splitting} |
| **Breaking Changes** | {None / Yes — description} |

---

## Summary

[Overall assessment: Is this change a net positive? High-level observations about the approach, architecture, and quality.]

## Findings

### Blockers

- **[Blocker]** `{file}:{line}` — {Description} (Confidence: {N}/100, Source: {category})
  - **Principle**: {Named engineering principle}
  - **Current**: `{code snippet}`
  - **Suggested**: `{fix snippet}`

### Improvements

- **[Improvement]** `{file}:{line}` — {Suggestion and rationale} (Confidence: {N}/100, Source: {category})
  - **Principle**: {Named engineering principle}
  - **Current**: `{code snippet}`
  - **Suggested**: `{fix snippet}`

### Questions

- **[Question]** `{file}:{line}` — {Clarification needed} (Source: {category})

### Praise

- **[Praise]** `{file}:{line}` — {What was done well and why it matters}

### Nitpicks

- **[Nit]** `{file}:{line}` — {Minor detail}

## Verdict

- **Recommendation**: {Approve / Request Changes / Approve with Nits}
- **Risk Level**: {Low / Medium / High / Critical}
- **Blockers**: {count}
- **Improvements**: {count}
- **Questions**: {count}
- **Nits**: {count}

---

GitHub PR Comment Format

Used in Phase 5 when --post-to-pr is enabled. Keep comments brief and link to code with full SHA.

Comment Template

### Code review

Found {N} issues:

1. {brief description} ({source}: "{evidence or CLAUDE.md quote}")

{link to file with full SHA and line range}

2. {brief description} ({source}: "{evidence}")

{link to file with full SHA and line range}

---

Generated with [Claude Code](https://claude.ai/code)

<sub>If this review was useful, react with :+1:. Otherwise, react with :-1:.</sub>

Clean Review Comment

### Code review

No issues found. Checked for bugs, security issues, and CLAUDE.md compliance.

---

Generated with [Claude Code](https://claude.ai/code)

Code Link Format

Links MUST use full SHA and line range:

https://github.com/{owner}/{repo}/blob/{full-sha}/{path/to/file}#L{start}-L{end}

• Use full 40-character SHA (not abbreviated)
• Include at least 1 line of context before and after
• Repo name must match the repo being reviewed
• Get the full SHA via: git rev-parse HEAD