/pr-prep

name: pr-prep
description: Prepares pull requests by running quality gates, drafting descriptions, and validating tests. Use when completing a feature and ready for review.
alwaysApply: false
category: artifact-generation
tags:
- git
- pr
- pull-request
- quality-gates
- testing
tools: []
complexity: medium
estimated_tokens: 1000
progressive_loading: true
modules:
- quality-gates.md
- pr-template.md
dependencies:
- sanctum:git-workspace-review
- imbue:proof-of-work
- imbue:justify
- imbue:structured-output
- scribe:slop-detector
- scribe:doc-generator

Pull Request Preparation Workflow

When NOT To Use

• Reviewing someone else's PR (use `sanctum:pr-review`)
• Only the commit message is needed (use `sanctum:commit-messages`)

Usage

Use this skill to stage changes and generate a PR summary. Run `Skill(sanctum:git-workspace-review)` first to capture the repository state and diffs.

Required Progress Tracking

Create progress items for these steps before starting: 1. `pr-prep:workspace-reviewed` 2. `pr-prep:quality-gates` 3. `pr-prep:self-reviewed` 4. `pr-prep:changes-summarized` 5. `pr-prep:testing-documented` 6. `pr-prep:pr-drafted` 7. `pr-prep:content-verified`

Mark each item as complete as the section is finished.

Step 1: Review Workspace (`workspace-reviewed`)

Confirm that `Skill(sanctum:git-workspace-review)` is complete. If changes were staged after the initial review, re-execute the skill to refresh the context.

Step 2: Run Quality Gates (`quality-gates`)

Execute formatting, linting, and tests using project-specific commands (e.g., `make lint`, `make test`). Resolve all failures before proceeding. If a task cannot be executed locally, document the reason and the alternative validation performed. Language-specific commands and failure handling are detailed in `modules/quality-gates.md`.

Capabilities Reference Sync

If any plugin files changed (plugin.json, skills, commands, agents, or hooks), run `make docs-sync-check` to verify `book/src/reference/capabilities-reference.md` is current. If it reports discrepancies, run `/sync-capabilities --fix` or update the reference manually before proceeding.

Step 2.5: Self-Review Pass (`self-reviewed`)

Read the diff as if you are a reviewer seeing it for the first time. This catches scope creep, stale debug code, and unclear changes before anyone else spends time on them.

**Automated checks:**

# Check for debug statements left in
git diff --cached --name-only | xargs grep -nE \
  '(console\.log|print\(|debugger|TODO|FIXME|HACK|XXX)' \
  2>/dev/null || true

# Check for commented-out code blocks (3+ consecutive lines)
git diff --cached | grep -c '^+.*//.*[a-zA-Z]' || true

# Check for formatting-only commits mixed with feature work
git log --oneline $(git merge-base HEAD origin/master)..HEAD | \
  grep -iE '(fmt|format|lint|style|whitespace)' || true

**Additive bias audit:**

Run `Skill(imbue:justify)` to compute the additive bias score and check Iron Law compliance. If the score is YELLOW or above, justify each flagged signal before proceeding. If RED or STOP, rethink the approach.

**Manual verification:**

• [ ] Read the full diff: does every change serve the

stated goal?

• [ ] No debug statements or `TODO` markers left in
• [ ] No commented-out code blocks
• [ ] No formatting changes mixed with logic changes
• [ ] No fixup commits that should be squashed
• [ ] Additive bias score is GREEN or justified YELLOW
• [ ] Iron Law compliance: PASS (no test tampering)

If issues are found, fix them before proceeding.

Step 3: Summarize Changes (`changes-summarized`)

Start from the analyzer rather than from a fresh reading of the diff:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pr_prep_analyze.py" --base origin/main

It reads the branch's changed files and commits, sorts the files into feature, test, docs and other, flags any `!` breaking-change marker in a commit subject, reports the quality gates it can decide from the changed-file list (tests touched, docs touched, changes described), recommends a merge strategy, and prints a description scaffold. Pass `--reviewer-map <json>` to map path prefixes to reviewers, or `--json` to consume it as data.

A gate printed `unknown` (`null` in JSON) means the script evaluated nothing: it runs no test, lint or type check and makes no release decision, so `passes_checks` and `includes_breaking_changes` always read `unknown`. Treat `unknown` as "you must check this yourself", never as a pass. Step 2 is where `passes_checks` gets its answer.

Then use the notes from the workspace review and the analyzer's categories to identify the key points in the diffs, and group them into 2-4 paragraphs on the technical changes and their rationale. Note breaking changes, migrations, or documentation updates.

Step 4: Document Testing (`testing-documented`)

List each test command executed and its result. If tests were skipped, document the reason and the mitigation plan.

Attach a manual test plan when any of these hold:

• The change has no automated coverage.
• It touches a user-facing or CLI-facing flow.
• It is a bug fix. Give reproduce, fix, and verify steps, where the

reproduce step fails on the parent commit.

• It changes an external contract.

Write it as numbered steps, each stating its expected result. A step without an expected result is a step the reviewer cannot fail. Format and examples are in `modules/pr-template.md`.

Step 5: Draft the PR (`pr-drafted`)

Populate the template with the facts table (Who, Where, When), then the Why and What-and-how sections, then Test plan and Checklist. Write the title imperative and self-contained so it reads correctly in `git log` out of context.

All three table rows are filled on every PR. A row that does not apply says so (`External: none`, `on merge`) rather than being deleted, so a reader can tell an omitted blast radius from a blast radius of none.

Add issue references, screenshots, migration