git-pr

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

Do NOT use markdown tables to track linked issues. GitHub's auto-close machinery only fires on Fixes #N / Closes #N / Resolves #N keywords in the PR body or commits. A | Issue | Status | table is decorative — linked issues will not auto-close on merge, even if every row says "fixed". Always include the closing keyword as a bare line at the bottom of the body (or in a commit message).

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

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 Stacked PRs below), 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

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

Stacked PRs

When merging a PR whose head branch is the base of one or more open downstream PRs, deleting the head branch on merge will close every dependent PR. gh pr merge --delete-branch and the matching UI checkbox both delete the head branch — safe for leaf PRs, destructive for stack parents.

Pre-merge check

The data-gathering script (Step 1) already scanned for open PRs targeting the current branch as their base — read STACK_PARENT and the DEPENDENT_PR=<n> HEAD=<branch> lines from its output. If STACK_PARENT=true, this PR is the parent of a stack. To re-probe on demand:

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

Merge rules for stacked PRs

Re-targeting dependents

Before merging the parent, point each dependent at the parent's base so they don't auto-close when the parent's branch disappears:

# For each dependent PR returned above:
gh pr edit <dep-pr-num> --base "$(gh pr view --json baseRefName --jq .baseRefName)"

Once every dependent has been re-targeted (or you have explicitly chosen not to), it is safe to merge the parent with --delete-branch.

After a squash-merge: rebase dependents off the squashed commits

Re-targeting alone keeps the dependent open, but its diff is still wrong. When the parent is squash-merged (the release-please / conventional-commit default), its commits collapse into one new commit on the base with a fresh SHA — so a re-targeted dependent still carries the parent's original commits in its history and now double-counts the parent's work. Drop them by replaying only the dependent's own commits onto the updated base:

git fetch origin
git rebase --onto origin/main <old-parent-tip> <dependent-branch>
git push --force-with-lease origin <dependent-branch>
git log --oneline origin/main..HEAD   # verify: only the dependent's own commits

Capture <old-parent-tip> with git rev-parse <parent-branch> before merging the parent (the branch is deleted on merge, so grab the SHA first). A merge-merged parent keeps its patch-ids, so a plain git rebase origin/main auto-skips the duplicates instead — but squash is the common default, so assume the --onto form. If the dependent and the parent edited the same lines, expect a conflict here: resolve it once and let git rerere replay it across this and any sibling dependent (see the git-conflicts skill).

Stacked PRs get no CI until retargeted

CI configured with on: pull_request: branches: [main] only runs for PRs targeting main. A dependent PR based on a feature branch therefore shows no checks at all until it is re-targeted — its pre-merge verification falls to a local build/test run in the meantime. Retarget early (or verify locally); don't wait on a green check that will never appear while the PR's base is a feature branch.

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"
   

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

Quick Reference

Agentic Optimizations