Skip to content

pr-prep

PR preparation: git archaeology, test validation, structured PR body generation. Mandatory user review gate before submission. Triggers: "prepare PR", "PR prep", "submit PR", "create PR body", "write PR description".

Source: skills/pr-prep/SKILL.md

Systematic PR preparation that validates tests and generates high-quality PR bodies.

Overview

Prepares contributions by analyzing the target repo's conventions, git history, test coverage, and generating properly-formatted PR bodies.

When to Use: - Preparing a PR for an external repository - Contributing bug fixes or features

When NOT to Use: - Internal commits (use normal git workflow) - PRs to your own repositories

Workflow

Text Only
-1. Prior Work Check     -> BLOCKING: Final check for competing PRs
0.  Isolation Check      -> BLOCK if PR mixes unrelated changes
1.  Context Discovery    -> Understand target repo conventions
2.  Git Archaeology      -> Analyze commit patterns, PR history
3.  Pre-Flight Checks    -> Run tests, linting, build
4.  Change Analysis      -> Summarize what changed and why
4.5 Commit Split Advisor -> Suggest logical commit groups (manual)
5.  PR Body Generation   -> Create structured PR description
6.  USER REVIEW GATE     -> STOP. User must approve before submission.
7.  Submission           -> Only after explicit user approval

Phase 0: Isolation Check (BLOCKING)

CRITICAL: Run this FIRST. Do not proceed if PR mixes unrelated changes.

Commit Type Analysis

Bash
# Extract commit type prefixes from branch
git log --oneline main..HEAD | sed 's/^[^ ]* //' | grep -oE '^[a-z]+(\([^)]+\))?:' | sort -u

Rule: If more than one commit type prefix exists, the PR is mixing concerns.

File Theme Analysis

Bash
# List all files changed vs main
git diff --name-only main..HEAD

# Group by directory
git diff --name-only main..HEAD | cut -d'/' -f1-2 | sort -u

Isolation Checklist

Check Pass Criteria
Single commit type All commits share same prefix
Thematic files All changed files relate to PR scope
No main overlap Changes not already merged
Atomic scope Can explain in one sentence

DO NOT PROCEED IF ISOLATION CHECK FAILS.

CRITICAL: User Review Gate

NEVER submit a PR without explicit user approval.

After generating the PR body (Phase 5), ALWAYS:

  1. Write the PR body to a file for review
  2. Show the user what will be submitted
  3. STOP and ask: "Ready to submit? Review the PR body above."
  4. Wait for explicit approval before running gh pr create
Bash
# Write PR body to file
cat > /tmp/pr-body.md << 'EOF'
<generated PR body>
EOF

# Show user
cat /tmp/pr-body.md

# ASK - do not proceed without answer
echo "Review complete. Submit this PR? [y/N]"

Phase 3: Pre-Flight Checks

Bash
# Go projects
go build ./...
go vet ./...
go test ./... -v -count=1

# Node projects
npm run build
npm test

# Python projects
pytest -v

Pre-Flight Checklist

  • Code compiles without errors
  • All tests pass
  • No new linting warnings
  • No secrets or credentials in code

Phase 4.5: Commit Split Analysis (Suggestion-Only)

Analyze the branch diff and suggest logical commit groupings.

Bash
# Review the scope of changes
git diff --stat main..HEAD

Output a numbered list of suggested commits with file groups:

Text Only
Commit 1: [description] -- files: path/a.go, path/a_test.go
Commit 2: [description] -- files: path/b.go, path/c.go

Ordering: Infrastructure/migrations > Models/services > Controllers/views > Tests > VERSION/CHANGELOG. Each commit must be independently valid (no broken imports). If diff is < 50 lines across < 4 files, recommend a single commit.

See references/commit-split-advisor.md for full rules.

These are suggestions only. User reads and implements manually.

Phase 5: PR Body Generation

Standard Format

Markdown
## Summary

Brief description of WHAT changed and WHY. 1-3 sentences.
Start with action verb (Add, Fix, Update, Refactor).

## Changes

Technical details of what was modified.

## Test plan

- [x] `go build ./...` passes
- [x] `go test ./...` passes
- [x] Manual: <specific scenario tested>

Fixes #NNN

Key conventions: - Test plan items are checked [x] (you ran them before PR) - Fixes #NNN goes at the end

Phase 7: Submission (After Approval Only)

Bash
# Create PR with reviewed body
gh pr create --title "type(scope): brief description" \
  --body "$(cat /tmp/pr-body.md)" \
  --base main

Remember: This command should ONLY run after user explicitly approves.

Anti-Patterns

DON'T DO INSTEAD
Submit without approval ALWAYS stop for user review
Skip isolation check Run Phase 0 FIRST
Bundle lint fixes into feature PRs Lint fixes get their own PR
Giant PRs Split into logical chunks
Vague PR body Detailed summary with context
Skip pre-flight Always run tests locally

Examples

Prepare External PR Body

User says: "Prepare this branch for PR submission."

What happens: 1. Run isolation and pre-flight validation. 2. Build structured PR body with summary and test plan. 3. Pause for mandatory user review before submit.

Evidence-First PR Packaging

User says: "Generate a high-quality PR description with clear verification steps."

What happens: 1. Gather git archaeology and test evidence. 2. Synthesize concise rationale and change list. 3. Produce submit-ready body pending approval.

Troubleshooting

Problem Cause Solution
PR body is weak Missing context from commits/tests Re-run evidence collection and expand summary
Submission blocked Mandatory review gate not passed Get explicit user approval before gh pr create
Test plan incomplete Commands/results not captured Add executed checks and outcomes explicitly
Title/body mismatch Scope drift during edits Regenerate from latest branch diff and constraints

Reference Documents