Table of Contents

• Core Principle
• When to Use
• Scope Classification Framework
• Classification Examples
• Workflow
• Phase 1: Establish Scope Baseline
• Phase 2: Gather Changes
• Phase 3: Requirements Validation
• Phase 1.5: Version Validation (MANDATORY)
• Phase 4: Code Review with Scope Context
• Phase 5: Backlog Triage
• Details
• Suggested Approach
• Priority
• Phase 6: Generate Report
• PR #X: Title
• Scope Compliance
• Blocking (0)
• In-Scope (2)
• Suggestions (1)
• Backlog → GitHub Issues (3)
• Recommendation
• Phase 7: Knowledge Capture
• Knowledge Captured 📚
• Quality Gates
• Anti-Patterns to Avoid
• Don't: Scope Creep Review
• Don't: Perfect is Enemy of Good
• Don't: Blocking on Style
• Don't: Reviewing Unchanged Code
• Integration with Other Tools
• Exit Criteria

Scope-Focused PR Review

Review pull requests with discipline: validate against original requirements, prevent scope creep, and route out-of-scope findings to GitHub issues.

Core Principle

A PR review validates scope compliance, not code perfection.

The goal is to validate the implementation meets its stated requirements without introducing regressions. Improvements beyond the scope belong in future PRs.

When to Use

• Before merging any feature branch
• When reviewing PRs from teammates
• To validate your own work before requesting review
• To generate a backlog of improvements discovered during review

Scope Classification Framework

Every finding must be classified:

Category	Definition	Action
BLOCKING	Bug, security issue, or regression introduced by this change	Must fix before merge
IN-SCOPE	Issue directly related to stated requirements	Should address in this PR
SUGGESTION	Improvement within changed code, not required	Author decides
BACKLOG	Good idea but outside PR scope	Create GitHub issue
IGNORE	Nitpick, style preference, or not worth tracking	Skip entirely

Classification Examples

BLOCKING:

• Null pointer exception in new code path
• SQL injection in new endpoint
• Breaking change to public API without migration
• Test that was passing now fails

IN-SCOPE:

• Missing error handling specified in requirements
• Feature doesn't match spec behavior
• Incomplete implementation of planned functionality

SUGGESTION:

• Better variable name in changed function
• Slightly more efficient algorithm
• Additional edge case test

BACKLOG:

• Refactoring opportunity in adjacent code
• "While we're here" improvements
• Technical debt in files touched but not changed
• Features sparked by seeing the code

IGNORE:

• Personal style preferences
• Theoretical improvements with no practical impact
• Premature optimization suggestions

Workflow

Phase 1: Establish Scope Baseline

Before looking at ANY code, understand what this PR is supposed to accomplish.

Note: Version validation (Phase 1.5) runs AFTER scope establishment but BEFORE code review. See modules/version-validation.md for details.

Search for scope artifacts in order:

1. Plan file: Most authoritative (check spec-kit locations first, then root)

   # Spec-kit feature plans (preferred - structured implementation blueprints)
   find specs -name "plan.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null | head -100
   # Legacy/alternative locations
   ls docs/plans/ 2>/dev/null
   # Root plan.md (may be Claude Plan Mode artifact from v2.0.51+)
   cat plan.md 2>/dev/null | head -100
   

   Verification: Run the command with --help flag to verify availability.

2. Spec file: Requirements definition (check spec-kit locations first)

   find specs -name "spec.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null | head -100
   cat spec.md 2>/dev/null | head -100
   

   Verification: Run the command with --help flag to verify availability.

3. Tasks file: Implementation checklist (check spec-kit locations first)

   find specs -name "tasks.md" -type f 2>/dev/null | head -1 | xargs cat 2>/dev/null
   cat tasks.md 2>/dev/null
   

   Verification: Run the command with --help flag to verify availability.

4. PR description: Author's intent

   gh pr view <number> --json body --jq '.body'
   

   Verification: Run the command with --help flag to verify availability.

5. Commit messages: Incremental decisions

   gh pr view <number> --json commits --jq '.commits[].messageHeadline'
   

   Verification: Run the command with --help flag to verify availability.

Output: A clear statement of scope:

"This PR implements [feature X] as specified in plan.md. The requirements are:

1. [requirement]
2. [requirement]
3. [requirement]"

If no scope artifacts exist, flag this as a process issue but continue with PR description as the baseline.

Phase 2: Gather Changes

# Changed files list
gh pr diff <number> --name-only

# Full diff
gh pr diff <number>

# Statistics
gh pr view <number> --json additions,deletions,changedFiles,commits

Verification: Run the command with --help flag to verify availability.

Phase 3: Requirements Validation

Before detailed code review, check scope coverage:

• Each requirement has corresponding implementation
• No requirements are missing
• Implementation doesn't exceed requirements (overengineering signal)

Phase 1.5: Version Validation (MANDATORY)

Run version validation checks BEFORE code review.

See modules/version-validation.md for detailed validation procedures.

Quick reference:

1. Check if bypass requested (--skip-version-check, label, or PR marker)
2. Detect if version files changed in PR diff
3. If changed, run project-specific validations:
   • Claude marketplace: Check marketplace.json vs plugin.json versions
   • Python: Check pyproject.toml vs version
   • Node: Check package.json vs package-lock.json
   • Rust: Check Cargo.toml vs Cargo.lock
4. Validate CHANGELOG has entry for new version
5. Check README/docs for version references
6. Classify findings as BLOCKING (or WAIVED if bypassed)

All version mismatches are BLOCKING unless explicitly waived by maintainer.

Phase 4: Code Review with Scope Context

Use pensive:unified-review on the changed files.

Critical: Evaluate each finding against the scope baseline:

**Verification:** Run the command with `--help` flag to verify availability.
Finding: "Function X lacks input validation"
Scope check: Is input validation mentioned in requirements?
  - YES → IN-SCOPE
  - NO, but it's a security issue → BLOCKING
  - NO, and it's a nice-to-have → BACKLOG

Verification: Run the command with --help flag to verify availability.

Phase 5: Backlog Triage

For each BACKLOG item, create a GitHub issue:

gh issue create \
  --title "[Tech Debt] Brief description" \
  --body "## Context
Identified during PR #<number> review.

## Details
<what the improvement would address>

## Suggested Approach
<how to implement>

## Priority
Low - Improvement opportunity, not blocking

---
*Auto-created by pr-review*" \
  --label "tech-debt"

Verification: Run the command with --help flag to verify availability.

Ask user before creating: "I found N backlog items. Create GitHub issues? [y/n/select]"

Phase 6: Generate Report

Structure the report by classification:

## PR #X: Title

### Scope Compliance
**Requirements:** (from plan/spec)
1. [x] Requirement A - Implemented
2. [x] Requirement B - Implemented
3. [ ] Requirement C - **Missing**

### Blocking (0)
None - no critical issues found.

### In-Scope (2)
1. [S1] Missing validation for edge case
   - Location: api.py:45
   - Requirement: "Handle empty input gracefully"

### Suggestions (1)
1. [G1] Consider extracting helper function
   - Author's discretion

### Backlog → GitHub Issues (3)
1. #142 - Refactor authentication module
2. #143 - Add caching layer
3. #144 - Update deprecated dependency

### Recommendation
**APPROVE WITH CHANGES**
Address S1 (in-scope issue) before merge.

Verification: Run the command with --help flag to verify availability.

Phase 7: Knowledge Capture

After generating the report, evaluate findings for knowledge capture into the project's review chamber.

Trigger: Automatically for findings scoring ≥60 on evaluation criteria.

# Capture significant findings to review-chamber
# Uses memory-palace:review-chamber evaluation framework

Verification: Run the command with --help flag to verify availability.

Candidates for capture:

• BLOCKING findings with architectural context → decisions/
• Recurring patterns seen in multiple PRs → patterns/
• Quality standards and conventions → standards/
• Post-mortem insights and learnings → lessons/

Output: Add to report:

### Knowledge Captured 📚

| Entry ID | Title | Room |
|----------|-------|------|
| abc123 | JWT over sessions | decisions/ |
| def456 | Token refresh pattern | patterns/ |

View: `/review-room list --palace <project>`

Verification: Run the command with --help flag to verify availability.

See modules/knowledge-capture.md for full workflow.

Quality Gates

A PR should be approved when:

• All stated requirements are implemented
• No BLOCKING issues remain
• IN-SCOPE issues are resolved or acknowledged
• BACKLOG items are tracked as GitHub issues
• Tests cover new code paths

Anti-Patterns to Avoid

Don't: Scope Creep Review

"While you're here, you should also refactor X, add feature Y, and fix Z in adjacent files."

Do: Create backlog issues, keep PR focused.

Don't: Perfect is Enemy of Good

"This works but could be 5% more efficient with different approach."

Do: If it meets requirements and has no bugs, it's ready.

Don't: Blocking on Style

"I prefer tabs over spaces."

Do: Use linters for style, reserve review for logic.

Don't: Reviewing Unchanged Code

"The file you imported from has some issues..."

Do: That's a separate PR. Create an issue if important.

Integration with Other Tools

• /fix-pr: After review identifies issues, use this to address them
• /pr: To prepare a PR before review
• pensive:unified-review: For the actual code analysis
• pensive:bug-review: For deeper bug hunting if needed

Exit Criteria

• Scope baseline established
• All changes reviewed against scope
• Findings classified correctly
• Backlog items tracked as issues
• Clear recommendation provided

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag