git-pr（git 公关）

Git PR

Create pull requests with comprehensive descriptions and proper issue linkage.

When to Use This Skill

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

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

Write the PR body to a tempfile with the Write tool, then pass it via --body-file. This sidesteps shell quoting entirely — backticks, code fences, and shell metacharacters are preserved byte-for-byte. See the Body content rule in github-issue-writing for the canonical guidance and the threshold for when bare --body "..." is still acceptable.

# 1) Write tool → /tmp/pr-body.md (no shell escaping involved)
# 2) gh pr create --body-file
gh pr create \
  --title "feat(scope): add feature" \
  --body-file /tmp/pr-body.md

Body content of /tmp/pr-body.md:

## 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

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

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-file /tmp/pr-body.md

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

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"

1. 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"

1. 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

Quick Reference

Agentic Optimizations