Enrich PR Description

Analyze branch changes and git history to build a rich PR description with three sections: a contextual summary, related issues/PRs, and people to CC.

When to Use

• User asks to create a PR (before gh pr create)
• User asks to improve/fix a PR description
• A PR has an empty or sparse body
• User asks who to CC or what to reference

Workflow

1. Gather Context

Run these in parallel to understand the full picture:

# Current branch and diff against base
git log --oneline main..HEAD
git diff main...HEAD

# PR if it already exists
gh pr view --json number,title,body,url,baseRefName,headRefName 2>/dev/null

2. Investigate the "Why"

For each changed file, dig into the history to understand the origin of the problem:

# Blame the changed lines on the base branch to find who introduced them
git blame main -- <file> | sed -n '<start>,<end>p'

# Show the originating commit
git log -1 --format='%H %an <%ae> %s' <commit-sha>

# Find the PR that introduced the commit
gh pr list --search "<commit-sha-prefix> OR <ticket-id>" --state merged --json number,title,author,url

Key questions to answer:

• What is the root cause of the problem?
• Is this a permanent vs transient condition being mishandled?
• What contract or convention was violated?
• Is there a sibling/similar function that handles the same case correctly?

3. Find Related Issues and PRs

Search for related work using ticket IDs, keywords, and function names:

# By ticket ID from branch name or commit messages
gh pr list --search "<TICKET-ID>" --state all --json number,title,author,url,state

# By keywords from the change
gh pr list --search "<keyword>" --state all --limit 10 --json number,title,author,url,state

Classify each related PR/issue:

• Origin -- introduced the code being fixed
• Related -- touches the same area or feature
• Alternate -- different approach to the same problem
• Blocked by / Blocks -- dependency relationship

4. Identify People to CC

From git blame and related PRs, collect GitHub usernames of people who:

• Authored the code being changed (from git blame)
• Authored related open PRs in the same area
• Are reviewers on related PRs

Extract GitHub usernames from PR data:

gh pr view <number> --json author --jq '.author.login'

5. Compose the Description

Use this structure:

## Summary

[2-4 sentences explaining WHAT changed and WHY. Focus on the root cause
and why the previous behavior was wrong. Include the mechanism of failure.]

> [!NOTE]
> [Optional callout for additional context, such as a sibling function
> that handles the same case correctly, or a related convention.]

## Related

- #<number> -- <relationship>: <brief description>
- #<number> -- <relationship>: <brief description>

CC @<username> @<username>

6. Apply the Description

For an existing PR:

gh pr edit <number> --body "$(cat <<'EOF'
<composed description>
EOF
)"

For a new PR, pass it to gh pr create --body.

Quality Checks

• Summary explains the root cause, not just the symptom
• Summary describes the mechanism (how the bug manifests)
• Related PRs include the one that introduced the issue
• Each related PR has a relationship label (origin, related, alternate)
• CC list includes the author of the originating code
• No speculative CC -- only people with direct involvement