/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] [--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

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 --stack

# Override the base branch (default: master)
/pr-review 123 --stack --base main

# Force single-PR mode even if a stack is detected
/pr-review 123 --no-stack

**Behavior**:

1. Before running its main workflow, `/pr-review` loads `Skill(sanctum:stack-mode)` to resolve the stack. Detection uses three strategies: branch-name convention (`stack/<feat>/<slice>`), the `## Stack` summary comment posted by `stack-push`, and a base-chain walk. 2. Without `--stack` but with a detected stack of size >= 2, the command prompts before iterating. Default is single-PR mode. 3. With `--stack`, the main review workflow runs once per PR in base-to-tip order. Per-PR outputs (review comment, test plan, description update) remain mandatory and unchanged. 4. After successful iteration, one stack summary comment is posted on the root PR listing each PR, its status, and a link to its per-PR review comment. 5. If any PR fails its mandatory outputs, iteration halts. Downstream PRs are left untouched because their review context may now be stale.

**Stack-mode contract**: see `Skill(sanctum:stack-mode)` for the shared detection, iteration, and summary format used by both `/pr-review --stack` and `/fix-pr --stack`.

Workflow Summary

1. **Scope Establishment** - Discover requirements from plan/spec/tasks 2. **Version Validation** - Ensure version consistency (mandatory unl