Git PR

Create pull requests with comprehensive descriptions and proper issue linkage.

When to Use This Skill

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 REFERENCE.md § Post-Merge Follow-up Issues.

1. Assess PR Readiness

Run the data-gathering script. It fetches the base ref, computes the ahead-count against origin/main, probes for an existing PR (via the state field — never merged), scans for stacked dependents, and audits closing keywords:

bash "${CLAUDE_SKILL_DIR}/scripts/git-pr.sh" --home-dir "$HOME" --project-dir "$(pwd)" --base origin/main

Parse STATUS= and ISSUES: from the output. Read PR_READY (false when AHEAD_COUNT=0 — nothing to PR), EXISTING_PR (a number means gh pr view / gh pr edit instead of creating), CURRENT_BRANCH, STACK_PARENT / DEPENDENT_PR=<n> (see REFERENCE.md § Stacked PRs), and BODY_NOT_AUTOCLOSING (see Step 5). Authoring the PR body remains your job.

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

For a short body you can skip the tempfile and stream it over stdin with --body-file - and a quoted heredoc:

gh pr create --title "feat(scope): add feature" --body-file - <<'EOF'
## Summary
Use `code`, ${vars}, and $shell syntax freely — they render verbatim.
EOF

Inside <<'EOF' (quoted delimiter), backticks, $, and \ are already literal — never backslash-escape them. A reflexive \`` survives into the rendered PR description and needs a follow-up gh pr edit --body-fileto clean up. (TheWritetool →--body-file` path above sidesteps the question entirely and stays the default for non-trivial bodies.)

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

5. Verify Closing Keywords

After the PR is created, audit the body: every issue referenced by number must have a matching Fixes / Closes / Resolves keyword. Issues mentioned only in a markdown table or prose will not auto-close on merge.

Re-run the data-gathering script against the just-created PR's body (write it to a tempfile first, or pass the fetched body) — it emits BODY_REFERENCED, BODY_CLOSING, and BODY_NOT_AUTOCLOSING:

gh pr view --json body --jq .body > /tmp/pr-body-check.md
bash "${CLAUDE_SKILL_DIR}/scripts/git-pr.sh" --home-dir "$HOME" --project-dir "$(pwd)" --body-file /tmp/pr-body-check.md

If BODY_NOT_AUTOCLOSING is non-empty, edit the PR body with gh pr edit <num> --body-file ... to add Fixes #N / Closes #N lines for any issue this PR is meant to close. Related: #N is correct for issues the PR references but does not close — those should not appear in the warning if you re-run the check.

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

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.

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

For the full PR description template, main-branch push pattern, stacked-PR merge rules, and the post-merge follow-up issue workflow, see REFERENCE.md.