/prepare-pr

name: prepare-pr
aliases: [pr]
description: Prepare a PR end-to-end by updating documentation, running tests, dogfooding checks, and validating with code review.
usage: /prepare-pr [--no-code-review] [--reviewer-scope strict|standard|lenient] [--skip-updates] [destination-file]
extends: "superpowers:receiving-code-review"

Complete PR Preparation Workflow

Orchestrates the full PR preparation workflow by running documentation updates, dogfooding checks, README updates, and test reviews before validating with code review. This is the "one command to prepare everything" before submitting a PR.

Key Features

• **Documentation Updates**: Runs `/sanctum:update-docs` to sync documentation
• **Dogfooding Checks**: Runs `/abstract:make-dogfood` to update Makefile demonstrations
• **README Sync**: Runs `/sanctum:update-readme` to keep README current
• **Test Coverage**: Runs `/sanctum:update-tests` to review test quality
• **Workspace Validation**: Uses sanctum:git-workspace-review for repository state analysis
• **Quality Gates**: Runs project-specific formatting, linting, and tests
• **Code Review Integration**: uses superpowers:receiving-code-review for automated review
• **Scope Compliance**: Validates changes against branch requirements
• **PR Template Generation**: Creates PR descriptions from the shared template

When To Use

• **Before every PR**: Complete preparation workflow
• **Feature completion**: Ensures all documentation and tests are current
• **Governance compliance**: Follows Mandatory Post-Implementation Protocol
• **Quality assurance**: Full validation before requesting reviews

When NOT To Use

• Simple changes that don't need the full workflow
• Work already completed through another sanctum command

Workflow

Phase 0: Pre-Flight Updates (NEW)

Unless `--skip-updates` is specified:

1. **Update Documentation**

   /sanctum:update-docs

• Syncs technical documentation
• Updates guides and references
• Ensures documentation completeness

2. **Update Makefile Dogfooding**

   /abstract:make-dogfood

• Updates Makefile demonstration targets
• Ensures Makefile reflects current features
• Validates make targets work correctly

3. **Update README**

   /sanctum:update-readme

• Syncs README with new features
• Updates command listings
• Refreshes examples and usage

4. **Update Tests**

   /sanctum:update-tests

• Reviews test coverage
• Identifies missing tests
• Validates test quality

Phase 1: Foundation (Sanctum)

5. **Workspace Review**

   Skill(sanctum:git-workspace-review)

• Captures repository status and diffs
• Identifies staged changes
• Establishes branch context

6. **Quality Gates**

   # Project-specific commands detected automatically
   make lint  # or equivalent (formats, then checks)
   make test  # or equivalent

Phase 2: Code Review (Superpowers)

7. **Automated Code Review**

   Skill(superpowers:receiving-code-review)

• Reviews staged changes against best practices
• Identifies potential issues before human review
• Generates review findings and recommendations

Phase 3: Synthesis

8. **PR Template Generation**

• Combines workspace analysis with code review findings
• Generates detailed PR description
• Includes quality gates results and review recommendations
• Verifies content quality via `scribe:slop-detector` principles
• Applies `scribe:doc-generator` guidelines to avoid AI-sounding text

Options

• `--skip-updates`: Skip documentation/dogfooding/README/test updates (Phase 0)
• `--no-code-review`: Skip superpowers code review (faster, less detailed)
• `--reviewer-scope`: Set review strictness (default: standard)
• `destination-file`: Output path for PR description (default: pr_description.md)

Reviewer Scope Levels

Strict

• All suggestions must be addressed
• detailed validation
• Suitable for critical code paths

Standard (Default)

• Balanced approach
• Critical issues must be fixed
• Suggestions are recommendations

Lenient

• Focus on blocking issues only
• Minimal validation
• Suitable for experimental features

Output Structure

The generated PR description includes:

Section names come from `sanctum:pr-prep/modules/pr-template.md`, which is the source of record. Keep this block in sync with it. The pytest contract in `plugins/sanctum/tests/test_pr_template_contract.py` fails if they drift.

[Imperative, self-contained title]

| | |
|---|---|
| **Who** | audience for the change; out-of-band reviewer if any |
| **Where** | internal: module + file count. External: consumers, or `none` |
| **When** | `on merge`, or the flag / migration window / integration date |

## Why
[Motivating problem, why merging now matters, linked issue]

## What and how
[What changed in the reader's terms; approach and rejected
alternative when a real decision point existed]

## Test plan
1. `make test`: 142/142 passing
2. `make lint`: clean (2 warnings)
3. Manual: [command] Expected: [observable result]

## Quality gates
- [x] Formatting: passed
- [x] Linting: passed (2 warnings)
- [x] Tests: passed (142/142)

## Code review findings
### Critical issues (0)
### Suggestions (3)
### Observations (2)

## Checklist
- [ ] Tests fail if the change is reverted
- [ ] Docs updated (README, Makefile dogfooding, capabilities reference)
- [ ] Breaking changes stated in the Where row
- [ ] One logical change per PR (no bundled formatting or unrelated refactors)
- [ ] Agent-generated code curated (no redundant implementations or premature abstractions)

`Quality gates` and `Code review findings` are specific to this command, which runs the gates itself. The plain `pr-prep` workflow emits the template without them.

Error Handling

Quality Gate Failures

# If quality gates fail
Error: Linting failed with 3 errors
Run 'ma