git-pr

Git PR

Create pull requests with comprehensive descriptions and proper issue linkage.

When to Use

Use this skill when...	Use X instead when...
Creating a new PR	Just crafting a title (github-pr-title)
Full PR workflow	Just pushing (git-push)
Submit for review	Just committing (git-commit)

PR Description Format

Standard Template

## Summary
Brief description of what this PR does.

## Motivation
Why this change is needed. Link to issue if applicable.

## Changes
- Key change 1
- Key change 2
- Key change 3

## Pre-merge Checklist
- [ ] Tests pass locally
- [ ] Code reviewed
- [ ] Documentation updated (if needed)

## Follow-up Issues
<!-- Post-merge actions tracked as separate issues so they survive PR closure -->
- Closes #456 after merge: database migration for new schema
- Refs #457: update deployment runbook

## Related Issues
Fixes #123
Related: #124, #125

Section Guidelines

Section	Purpose	Required
Summary	What the PR does (1-2 sentences)	Yes
Motivation	Why this change is needed	Yes
Changes	Key changes as bullet points	Yes
Pre-merge Checklist	Actions before merge only — never post-merge steps	If applicable
Follow-up Issues	Links to issues tracking post-merge actions	If post-merge work exists
Related Issues	Issue links at bottom	Yes

Issue Linking Syntax

Place at the bottom of the PR description:

## Related Issues
Fixes #123              <!-- Auto-closes on merge -->
Closes #456             <!-- Auto-closes on merge -->
Resolves #789           <!-- Auto-closes on merge -->
Related: #124, #125     <!-- Links without closing -->

Rules:

• Use Fixes, Closes, or Resolves for issues this PR solves
• Use Related: for issues that are related but not solved
• Follow-up work should be created as new issues, not left in checklist

Workflow

Before creating the PR, check whether any post-merge follow-up actions are needed (migrations, deployments, config changes, runbook updates). Create a GitHub issue for each and link them in the PR description. See Post-Merge Follow-up Issues.

1. Assess PR Readiness

# Check current branch
git branch --show-current

# Fetch latest remote state for accurate comparison
git fetch origin main

# Check commits ahead of origin/main (always compare against remote)
ahead=$(git rev-list --count origin/main..HEAD 2>/dev/null || echo "0")
if [ "$ahead" = "0" ]; then
  echo "No commits ahead of origin/main - nothing to create PR for"
  exit 1
fi

# Check for existing PR
gh pr view --json number,state 2>/dev/null || echo "no existing PR"

2. Analyze Commits

CRITICAL: Always compare against origin/main (not local main) to avoid including commits that haven't been merged to the remote. Local main may be ahead of origin/main with unrelated commits.

# Fetch latest remote state
git fetch origin main

# Always use origin/main as base reference
base_ref="origin/main"

git log $base_ref..HEAD --format='%H %s'

# Extract issue references
git log $base_ref..HEAD --format='%B' | grep -oE '#[0-9]+' | sort -u

# Get diff stats
git diff $base_ref...HEAD --stat

3. Identify Post-Merge Follow-ups and Create Issues

Before creating the PR, scan for any actions required after the PR is merged (deployments, migrations, config changes, external docs). For each:

# Create a follow-up issue
gh issue create \
  --title "[Chore] DB: Run migration for new schema" \
  --body "Follow-up to PR that adds user_preferences.\n\nRun: rake db:migrate in production after deploy."
# Returns: https://github.com/org/repo/issues/456

Keep a list of created issue numbers to link in the PR body.

4. Create PR

gh pr create \
  --title "feat(scope): add feature" \
  --body "$(cat <<'EOF'
## Summary
Brief description of what this PR does.

## Motivation
Why this change is needed.

## Changes
- Change 1
- Change 2

## Pre-merge Checklist
- [ ] Tests pass locally
- [ ] Code reviewed

## Follow-up Issues
- #456: run database migration after deploy
- #457: update production config

## Related Issues
Fixes #123
Related: #456
EOF
)"

PR Title Format

Use conventional commits format (see github-pr-title skill):

<type>(<scope>): <subject>

Examples:

• feat(auth): add OAuth2 support
• fix(api): handle null response
• docs(readme): update installation

PR Options

Option	Command
Draft	gh pr create --draft
Labels	gh pr create --label "enhancement"
Reviewers	gh pr create --reviewer user1,user2
Base branch	gh pr create --base develop
Assignee	gh pr create --assignee @me

Main-Branch Development

When on main, push to remote feature branch:

# Push main to remote feature branch
git push origin main:feat/feature-name

# Create PR with --head
gh pr create --head feat/feature-name --base main --title "..." --body "..."

Pre-merge Checklist Guidelines

Include only actions before merging:

• Tests pass locally
• Code reviewed
• Documentation updated
• Breaking changes documented

Do NOT include post-merge steps in the checklist. PR descriptions are closed and buried after merge — checklists embedded there are easily missed. Post-merge actions must be tracked as GitHub issues.

Post-Merge Follow-up Issues

When a PR requires actions after it is merged, create a separate GitHub issue for each follow-up. Link all follow-up issues in the PR description under a Follow-up Issues section.

Why issues, not PR checklists: Once a PR is merged and closed, its description is rarely revisited. A GitHub issue stays open and assignable until explicitly closed, ensuring the follow-up is not lost.

Common post-merge follow-up types

Type	Example follow-up issue title
Database migration	[Chore] DB: Run schema migration for user_preferences table
Deployment	[Chore] Ops: Deploy feature-flag config to production
Manual configuration	[Chore] Config: Enable new OAuth provider in admin panel
External documentation	[Docs] Wiki: Update runbook for new deploy process
Communication	[Chore] Comms: Announce deprecation of /v1 API to customers
Dependent PR	[Feature] Next: Implement follow-on X after Y lands

Workflow

1. Identify post-merge actions from commit messages, PR body, or conversation context.
2. Create an issue for each follow-up:

   gh issue create \
     --title "[Chore] DB: Run migration for new schema" \
     --body "After #42 merges, run: \`rake db:migrate\` in production.\n\nSee PR #42 for context." \
     --label "chore"
   

3. Link the newly created issues in the PR description:

   gh pr edit <pr-number> --body "$(gh pr view <pr-number> --json body -q '.body')
   
   ## Follow-up Issues
   - #<issue-num>: run database migration
   - #<issue-num>: update deployment runbook"
   

4. Do NOT add post-merge steps to the Pre-merge Checklist.

Example: PR description with follow-up issues

## Follow-up Issues
<!-- These issues track post-merge work and will stay open until completed -->
- #456: run database migration for user_preferences table
- #457: update production feature-flag config

Output

On success, report:

Created PR #42: feat(auth): add OAuth2 support
URL: https://github.com/org/repo/pull/42

Related Issues:
  Fixes #123
  Related: #456

Status: Open

Error Handling

Error	Solution
Branch not pushed	Push first or use main-branch pattern
PR exists	gh pr view or gh pr edit
No commits	Commit changes first

Quick Reference

Action	Command
Create PR	gh pr create --title "..." --body "..."
Draft PR	gh pr create --draft
View PR	gh pr view
Edit PR	gh pr edit --title "..." --body "..."
List PRs	gh pr list
Check status	gh pr checks
Create follow-up issue	gh issue create --title "[Chore] ..." --body "..."

Agentic Optimizations

Context	Command
PR readiness	gh pr view --json number,state 2>/dev/null
Commits	git log origin/main..HEAD --format='%s'
Issue refs	git log origin/main..HEAD --format='%B' | grep -oE '#[0-9]+'
Create follow-up issue	gh issue create --title "[Chore] ..." --body "Follow-up to PR #N..."
Create PR	gh pr create --title "..." --body "..."