PR Prep

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)

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 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, screenshots, migration guides, or follow-up items as the change calls for them. Template structure, worked examples, and size variations are in modules/pr-template.md. The decision behind the structure, with its sources, is recorded in docs/adr/0021-pr-descriptions-in-two-registers.md.