/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"

# Claude Code 2.1.0+ lifecycle hooks
hooks:
  PreToolUse:
    - matcher: "Skill|Task"
      command: |
        # Log PR preparation start with options
        echo "[cmd:prepare-pr] PR preparation started at $(date) | User: ${USER:-unknown}" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        # Track code review option (important for quality metrics)
        if echo "$CLAUDE_TOOL_INPUT" | grep -q "no-code-review"; then
          echo "[cmd:prepare-pr] ⚠️  Option: --no-code-review (automated review SKIPPED)" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        fi
        # Track reviewer scope
        if echo "$CLAUDE_TOOL_INPUT" | grep -q "reviewer-scope"; then
          scope=$(echo "$CLAUDE_TOOL_INPUT" | grep -oP 'reviewer-scope["\s:=]+\K\w+')
          echo "[cmd:prepare-pr] Reviewer scope: ${scope:-standard}" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        fi
        # Track update skip option
        if echo "$CLAUDE_TOOL_INPUT" | grep -q "skip-updates"; then
          echo "[cmd:prepare-pr] ⚠️  Option: --skip-updates (documentation updates SKIPPED)" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        fi
      once: true
  PostToolUse:
    - matcher: "Bash"
      command: |
        # Log quality gate execution
        if echo "$CLAUDE_TOOL_INPUT" | grep -qE "(make|npm|cargo) (test|lint|fmt|build)"; then
          cmd=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command // empty' 2>/dev/null || echo 'N/A')
          echo "[cmd:prepare-pr] ✓ Quality gate executed: $cmd" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        fi
  Stop:
    - command: |
        echo "[cmd:prepare-pr] === PR preparation completed at $(date) ===" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/command-audit.log
        # Could push to PR metrics dashboard

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 structured PR descriptions

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 fmt  # or equivalent
   make lint  # or equivalent
   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