pr-prep

PR Preparation Skill

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

Folded trigger (ag-s43tg wave 1): pr-research routes here

• pr-research → upstream research mode. Use when you need to Research an upstream repo before contributing — systematic exploration of an external codebase as the FIRST step before planning or implementing an open source contribution: prior-work check (existing issues/PRs), mandatory CONTRIBUTING.md discovery, guidelines/templates analysis, PR archaeology on merged PRs and commit patterns, maintainer response-pattern research, and issue discovery for contribution opportunities. That research lane now lives at the front of this skill's workflow — Phase -1 (Prior Work Check) and Phase 1 (Context Discovery) absorb it; write the findings to .agents/research/YYYY-MM-DD-upstream-*.md before moving to commit/body prep.

---

Workflow

-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

# 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

# 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

# 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

# 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.

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

Output a numbered list of suggested commits with file groups:

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

## 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)

# 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

• references/pr-prep.feature — Executable spec: analyze repo conventions/history, validate tests first, generate PR body + branch (soc-qk4b)

• references/case-study-historical-context.md

• references/lessons-learned.md

• references/package-extraction.md

• references/commit-split-advisor.md