/pr-review

name: pr-review
description: Review pull requests with scope validation, code analysis, and line comments. Supports GitHub PRs and GitLab MRs.
usage: /pr-review [<pr-number> | <pr-url> | <mr-url>] [--scope-mode strict|standard|flexible] [--auto-approve-safe-prs] [--no-auto-issues] [--no-insights] [--dry-run] [--local [path]] [--no-line-comments] [--concise] [--hold-insights] [--skip-version-check] [--skip-doc-review] [--stack] [--no-stack] [--base <branch>]
extends: "superpowers:receiving-code-review"

Enhanced PR/MR Review

Integrates Sanctum's disciplined scope validation with superpowers:receiving-code-review's detailed analysis to provide thorough, balanced reviews that prevent scope creep while ensuring code quality. Supports both GitHub PRs and GitLab MRs via `leyline:git-platform` detection.

Core Philosophy

**Scope-Aware Quality Validation**

• Validate implementation against stated requirements
• Prevent overengineering through scope discipline
• validate code quality without blocking valid implementations
• Route out-of-scope improvements to backlog

Key Enhancements

Sanctum Contributions

• **Scope Baseline Establishment**: Analyzes plan/spec artifacts
• **Requirements Compliance Checking**: Validates against original specs
• **Automatic Issue Creation**: Out-of-scope items are automatically logged to GitHub issues
• **Structured Reporting**: Clear classification of findings

Superpowers Contributions

• **Automated Code Analysis**: Deep review of implementation quality
• **Best Practice Validation**: Industry-standard checks
• **Security Scanning**: Vulnerability detection
• **Performance Impact Assessment**: Efficiency considerations

When To Use

• Reviewing feature branch PRs
• Validating implementation against requirements
• Pre-merge quality gates
• Generating actionable review feedback
• Creating improvement backlog

When NOT To Use

• Self-reviewing trivial changes
• Draft PRs not ready for review

Documentation

| Document | Purpose | |----------|---------| | **[Workflow Details](pr-review/modules/review-workflow.md)** | Detailed review phases, examples, advanced features | | **[Classification Framework](pr-review/modules/review-framework.md)** | Review classification system and scope modes | | **[Configuration & Options](pr-review/modules/review-configuration.md)** | Command options, configuration, best practices |

Quick Start

Basic Usage

# Review PR/MR with default settings
/pr-review 123

# Review with platform URL
/pr-review https://github.com/org/repo/pull/123
/pr-review https://gitlab.com/org/repo/-/merge_requests/123

Scope Modes

# Strict scope enforcement
/pr-review --scope-mode strict

# Standard (balanced) - default
/pr-review --scope-mode standard

# Flexible (minimal blocking)
/pr-review --scope-mode flexible

Common Options

# Dry run (no comments posted)
/pr-review --dry-run

# Write report to local .md file instead of posting to PR
/pr-review --local
/pr-review --local reviews/my-review.md

# Auto-approve safe PRs
/pr-review --auto-approve-safe-prs

# Skip automatic issue creation for out-of-scope items (issues are created by default)
/pr-review --no-auto-issues

# Skip posting review findings as Insights to Discussions (insights posted by default)
/pr-review --no-insights

# Skip version consistency check
/pr-review --skip-version-check

# Socratic comprehension loop: you explain the diff, the agent probes gaps
/pr-review --interactive

# Minimal review: inline suggestion blocks plus one short summary, nothing else
/pr-review https://gitlab.com/org/repo/-/merge_requests/123 --concise

# Hold direction and architecture feedback in chat; post only what you select
/pr-review 123 --hold-insights

# The two compose: terse on the MR, judgment calls settled here first
/pr-review 123 --concise --hold-insights

Concise Mode

`--concise` is for a reviewer who wants the MR to carry the fix and nothing more. Each finding on a diff line is posted as a suggestion block the author can apply with one click, and a sentence beside it only where the change would otherwise puzzle them. One short summary review closes it. The test-plan comment, the description update, and the Why / Proof / Teachable Moment paragraphs are not posted. Findings that do not fit a suggestion (a missing test, a design question) go in the summary as one line each.

Posting patterns for both platforms: `Skill(sanctum:pr-review)` module `modules/suggestion-comments.md`.

Held Insights

`--hold-insights` widens Phase 4.6. Every finding about the direction of the MR, its architecture, or an open question is presented in chat with the `[y/n/select]` prompt Phase 5 already uses for backlog issues, and only the selected items are posted. Nothing about `--no-insights` changes: that flag governs Discussions posting and stays on by default.

Interactive Mode

`--interactive` adds a comprehension loop to the review. You open each round by stating your understanding of a hunk, asking your own question, or admitting you do not follow it. The agent answers from the diff, then probes the gap your opening revealed.

Each exchange is graded and written to gauntlet's progress store, so weak areas steer both later probes and later `/gauntlet` challenges. Probe results never change the merge recommendation. They are reported in a Comprehension section.

Requires no `.gauntlet` knowledge base. See `Skill(sanctum:pr-review)` module `modules/interactive-review.md` for turn order, scoring, and the recording contract.

Stack Mode (Multi-PR Review)

When the target PR is part of a stack of dependent PRs rooted at a common base branch, `/pr-review` can review the entire stack in one invocation. Each PR still gets its own review comment, test plan, and PR description update; the root PR additionally receives a consolidated stack-level summary.

# Explicit: review the whole stack containing PR 123
/pr-review 123 --stac