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