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

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