/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
model_hint: standard
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
hooks:
  PreToolUse:
  - matcher: Bash
    command: "# Log quality gate execution\ncmd=$(jq -r '.tool_input.command // empty' 2>/dev/null || echo 'N/A')\nif echo \"$cmd\" | grep -qE \"(make|npm|cargo|pytest|ruff|eslint|clippy) (test|lint|fmt|build|check)\"; then\n  echo \"[skill:pr-prep] Quality gate: $cmd at $(date)\" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/skill-audit.log\nfi\n"
    once: false
  PostToolUse:
  - matcher: Write
    command: "# Track PR template generation\nfile=$(jq -r '.tool_input.file_path // empty' 2>/dev/null)\nif echo \"$file\" | grep -qE \"(pr[-_]description|PR[-_]TEMPLATE|pull[-_]request)\"; then\n  echo \"[skill:pr-prep] PR template written: $file at $(date)\" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/skill-audit.log\nfi\n"
  Stop:
  - command: 'echo "[skill:pr-prep] === Workflow completed at $(date) ===" >> ${CLAUDE_CODE_TMPDIR:-/tmp}/skill-audit.log

      '

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 `TodoWrite` 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`)

Use the notes from the workspace review and the output of `git diff --stat origin/main...HEAD` to understand the scope. Identify key points in the diffs and group them into 2-4 paragraphs highlighting 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, screenshot