Pull Request Skills

Guidelines for creating comprehensive pull request descriptions and submitting PRs efficiently.

Philosophy

• Reviewer-first - Optimize for the person reviewing, not the author
• Context over detail - Explain why, link to how
• Scannable - Busy reviewers skim; make it easy
• Actionable - Clear testing steps, obvious risks
• Honest - Flag complexity, don't hide it

Gathering Context

Before creating a PR, gather information about the changes:

# Compare branch changes against main
git diff main...HEAD

# List modified files
git diff main...HEAD --name-only

# Review commit history
git log main..HEAD --oneline

# Get detailed commit messages
git log main..HEAD --format="%B---"

# Get files changed with stats
git diff main...HEAD --stat

Quick Reference

Task	Guide
Sizing and splitting PRs	pr-sizing.md
Writing PR descriptions	pr-description.md
Creating PRs with gh CLI	pr-creation.md

When to Use Each Guide

PR Sizing

Use pr-sizing.md when you need:

• Size category definitions (small/medium/large)
• Signs a PR should be split
• Strategies for splitting large PRs
• Guidance on when large PRs are acceptable

PR Description Writing

Use pr-description.md when you need:

• Templates for small, medium, or large PRs
• Section writing guidelines (summary, changes, testing, etc.)
• Commands to gather context from git history

PR Creation

Use pr-creation.md when you need:

• gh pr create command syntax and options
• HEREDOC pattern for multi-line bodies
• Draft PRs, reviewers, labels, and milestones
• Troubleshooting common errors