| name | creating-pull-requests |
| description | Use this skill when creating pull requests, drafting PR descriptions, or running `gh pr create`. Ensures proper PR formatting with active-voice titles and structured descriptions explaining why, how, and context links. |
Creating Pull Requests
Create well-structured pull requests with clear titles and comprehensive descriptions.
Critical Rules
NEVER do these:
- Do NOT add yourself as a coauthor on commits (no
Co-Authored-Byheaders) - Do NOT include phrases like "Generated with Claude Code" or "Created by Claude"
- Do NOT mention AI or Claude anywhere in commits or PR descriptions
PR Title Format
Use active voice with a present-tense verb:
| Good | Bad |
|---|---|
| Add user authentication | Added user authentication |
| Fix memory leak in cache | Fixing memory leak |
| Update dependencies to latest | Dependency updates |
| Remove deprecated API endpoints | Removed deprecated API |
| Refactor database connection pool | Database refactoring |
Pattern: <Verb> <what> [to/in/for <context>]
Common verbs: Add, Fix, Update, Remove, Refactor, Implement, Improve, Replace, Enable, Disable
PR Description Structure
## Why
[Explain the motivation for this change. What problem does it solve? What feature does it enable?]
## Approach
[Explain why this implementation was chosen over alternatives. What trade-offs were considered?]
## How it works
[Describe the technical implementation. How does the code achieve the goal?]
## Links
- [Ticket](url) or JIRA-123
- [Slack thread](url)
Step-by-Step Process
1. Gather Context
Before creating the PR, understand what's being changed:
# See all commits on this branch vs main
git log main..HEAD --oneline
# See the full diff
git diff main...HEAD
# Check current branch name
git branch --show-current
2. Identify Links and References
Ask the user or search for:
- Jira/ticket numbers (look in commit messages or branch name)
- Related Slack conversations
- Fusion run URLs
- GCS paths for data or artifacts
3. Draft the PR
gh pr create --title "Add feature X to service Y" --body "$(cat <<'EOF'
## Why
[Motivation here]
## Approach
[Implementation rationale here]
## How it works
[Technical details here]
## Links
- [Ticket](url)
EOF
)"
Example
Branch: feature/add-retry-logic
Commits: Adds exponential backoff retry to HTTP client
Title: Add exponential backoff retry to HTTP client
Description:
## Why
HTTP requests to external services occasionally fail due to transient network issues. Without retry logic, these failures cascade to users as errors.
## Approach
Chose exponential backoff over fixed-interval retry to avoid thundering herd problems during partial outages. Used a max of 3 retries with jitter to spread out retry attempts.
## How it works
Wraps the existing HTTP client with a retry decorator. On 5xx responses or network errors, waits `2^attempt * 100ms + random(0-50ms)` before retrying. Logs each retry attempt for observability.
## Links
- [PROJ-1234](https://jira.example.com/browse/PROJ-1234)
- [Slack discussion](https://slack.com/archives/...)
CLI Commands
# Create PR interactively
gh pr create
# Create with title and body
gh pr create --title "Add X" --body "Description here"
# Create as draft
gh pr create --draft --title "Add X" --body "..."
# Create with specific base branch
gh pr create --base develop --title "Add X" --body "..."
# Create and immediately open in browser
gh pr create --title "Add X" --body "..." --web
Validation Checklist
Before creating the PR, verify:
- Title uses active voice with present-tense verb
- Description has Why, Approach, and How sections
- All relevant links are included
- No AI/Claude attribution anywhere
- No Co-Authored-By headers in commits