Creating Pull Requests

Creating Pull Requests

Overview

This skill ensures pull requests are comprehensive, accurate, and useful for future reference. PRs should document the COMPLETE set of changes in a branch, not just what was remembered from the current conversation. PRs must also link to related GitHub issues - most PRs have an associated issue, and these links are critical for tracking work and understanding context.

Critical Principles

1. Trust git, not memory - The git diff is the source of truth, not conversation history
2. Every changed file matters - Files are rarely changed by accident; all changes deserve documentation
3. PRs are searchable documentation - Titles and descriptions should contain keywords that help find this PR when debugging issues later
4. Complete > Concise - A thorough PR description is more valuable than a brief one
5. Most PRs close an issue - Actively search for related issues; don't assume none exist just because the user didn't mention one

Mandatory Workflow

When creating a pull request, execute these steps IN ORDER. Do not skip steps.

Step 1: Gather Complete Change Information

Run ALL of these commands to understand the full scope of changes:

# See all files that differ from the base branch
git diff --name-status $(git merge-base HEAD master)..HEAD

# See the full diff to understand what changed
git diff $(git merge-base HEAD master)..HEAD

# See all commits on this branch
git log --oneline $(git merge-base HEAD master)..HEAD

# Check for any uncommitted changes that should be included
git status

IMPORTANT: Read the FULL output of these commands. Do not skim or summarize prematurely.

Step 2: Search for Related GitHub Issues

Most PRs should close an issue. Before creating the PR, actively search for related issues.

# Search all issues (open and closed) to find any related context
gh issue list --search "keyword1 keyword2" --state all

# Example: If fixing email notifications, try multiple keyword variations:
gh issue list --search "email notification" --state all
gh issue list --search "notification not sent" --state all

Extract keywords from:

• The branch name (e.g., fix/email-notifications → search "email notifications")
• Commit messages from Step 1
• The problem being solved (what would someone have reported?)

If you find related issues:

• Note ALL issue numbers that this PR addresses
• The PR description MUST include Closes #XXX or Fixes #XXX for each

If no issues are found after searching:

• ASK THE USER: "I searched for related issues but didn't find any. Is there a GitHub issue this PR should close?"
• Do NOT proceed without confirming - the user may know of an issue you missed

Common rationalization to avoid:

"The user didn't mention an issue, so there probably isn't one"

This is wrong. Users often forget to mention issue numbers. Your job is to find them.

Step 3: Categorize All Changes

Group every changed file into categories. Common categories include:

• Bug fixes
• New features
• Refactoring
• Configuration changes
• Dependency updates
• Test additions/changes
• Documentation

Every file from the diff MUST appear in at least one category.

Step 4: Write a Comprehensive Title

The PR title should:

• Summarize the PRIMARY purpose of the changes
• Include keywords that would help find this PR later
• Be specific enough to distinguish from similar PRs

Good: fix(router): prevent redirect loop for API routes Bad: fix redirect issue

Step 5: Write the PR Description

The description MUST include:

Summary Section

• 2-5 bullet points covering the main changes
• Each major change category should have at least one bullet
• Reference specific files or components when helpful

Files Changed Section

List ALL changed files grouped by purpose. Example:

### Bug Fixes
- `src/router.ts` - Fixed redirect logic

### New Features
- `src/components/Feature.tsx` - Added new component

### Configuration
- `config/settings.json` - Updated default values

Test Plan Section

• How to verify the changes work
• Any manual testing steps required

Step 6: Self-Review Checklist

Before creating the PR, verify:

• Every file from git diff --name-status is mentioned in the description
• The title contains searchable keywords related to the changes
• The description explains WHY changes were made, not just WHAT changed
• Any breaking changes or migration steps are clearly documented
• Issue search completed - You searched GitHub issues with relevant keywords
• Issue linking resolved - Either: (a) PR includes Closes #XXX for found issues, OR (b) You asked the user and confirmed no issue exists

Common Mistakes to Avoid

Relying on Session Memory

Wrong: "I changed the router to fix redirects" Right: Run git diff and document ALL changes, including ones from earlier in the session or previous sessions

Omitting "Minor" Changes

Wrong: Leaving out config file changes because they seem unimportant Right: Every changed file is documented - config changes often matter for deployment

Vague Descriptions

Wrong: "Fixed some bugs and updated configs" Right: Specific descriptions of what was fixed and why, with file references

Forgetting Uncommitted Changes

Wrong: Creating PR with unstaged changes still pending Right: Run git status first and decide if pending changes should be committed

Assuming No Issue Exists

Wrong: "The user didn't mention an issue, so I'll just create the PR without one" Right: Search GitHub for related issues using keywords from the branch name and commit messages. If nothing found, ask the user before proceeding.

Treating Issue Links as Optional

Wrong: Fixes #1234 (if there was an issue) or skipping the search entirely Right: Always search for issues. Most PRs have one. Include Closes #XXX for every related issue found.

PR Description Template

Use this template structure:

## Summary
- [Primary change/fix with context]
- [Secondary changes]
- [Any additional notable changes]

Closes #XXX

## Changes

### [Category 1]
- `path/to/file.ext` - Description of change

### [Category 2]
- `path/to/file.ext` - Description of change

## Test Plan
- [ ] Step to verify change 1
- [ ] Step to verify change 2

## Notes
[Any additional context, breaking changes, or follow-up work needed]

Rationalizations That Mean You're About to Skip Issue Search

If you catch yourself thinking any of these, STOP. You are rationalizing skipping a required step.

All of these mean: Run gh issue list --search before creating the PR.