Generate PR Description
You are tasked with generating a comprehensive pull request description following the repository's standard template.
Steps to follow:
- •
Read the PR description template:
- •First, check if
.ai/thoughts/shared/pr_description.mdexists - •If it doesn't exist, inform the user they need to create a PR description template at
.ai/thoughts/shared/pr_description.md - •Read the template carefully to understand all sections and requirements
- •First, check if
- •
Identify the PR to describe:
- •Check if the current branch has an associated PR:
gh pr view --json url,number,title,state 2>/dev/null - •If no PR exists for the current branch, or if on main/master, list open PRs:
gh pr list --limit 10 --json number,title,headRefName,author - •Ask the user which PR they want to describe
- •Check if the current branch has an associated PR:
- •
Check for existing description:
- •Check if
.ai/thoughts/shared/prs/{number}_description.mdalready exists - •If it exists, read it and inform the user you'll be updating it
- •Consider what has changed since the last description was written
- •Check if
- •
Gather comprehensive PR information:
- •Get the full PR diff:
gh pr diff {number} - •If you get an error about no default remote repository, instruct the user to run
gh repo set-defaultand select the appropriate repository - •Get commit history:
gh pr view {number} --json commits - •Review the base branch:
gh pr view {number} --json baseRefName - •Get PR metadata:
gh pr view {number} --json url,title,number,state
- •Get the full PR diff:
4b. Gather reasoning history (if available):
- •Check if reasoning files exist:
ls .git/claude/commits/*/reasoning.md 2>/dev/null - •If they exist, aggregate them:
bash .claude/scripts/aggregate-reasoning.sh main - •This shows what approaches were tried before the final solution
- •Save the output for inclusion in the PR description
- •
Analyze the changes thoroughly: (ultrathink about the code changes, their architectural implications, and potential impacts)
- •Read through the entire diff carefully
- •For context, read any files that are referenced but not shown in the diff
- •Understand the purpose and impact of each change
- •Identify user-facing changes vs internal implementation details
- •Look for breaking changes or migration requirements
- •
Handle verification requirements:
- •Look for any checklist items in the "How to verify it" section of the template
- •For each verification step:
- •If it's a command you can run (like
make check test,npm test, etc.), run it - •If it passes, mark the checkbox as checked:
- [x] - •If it fails, keep it unchecked and note what failed:
- [ ]with explanation - •If it requires manual testing (UI interactions, external services), leave unchecked and note for user
- •If it's a command you can run (like
- •Document any verification steps you couldn't complete
- •
Generate the description:
- •Fill out each section from the template thoroughly:
- •Answer each question/section based on your analysis
- •Be specific about problems solved and changes made
- •Focus on user impact where relevant
- •Include technical details in appropriate sections
- •Write a concise changelog entry
- •If reasoning files were found (from step 4b):
- •Add an "## Approaches Tried" section before "## How to verify it"
- •Include the aggregated reasoning showing failed attempts and what was learned
- •This helps reviewers understand the journey, not just the destination
- •Ensure all checklist items are addressed (checked or explained)
- •Fill out each section from the template thoroughly:
- •
Save the description:
- •Write the completed description to
.ai/thoughts/shared/prs/{number}_description.md - •Show the user the generated description
- •Write the completed description to
- •
Update the PR:
- •Update the PR description directly:
gh pr edit {number} --body-file .ai/thoughts/shared/prs/{number}_description.md - •Confirm the update was successful
- •If any verification steps remain unchecked, remind the user to complete them before merging
- •Update the PR description directly:
Important notes:
- •This command works across different repositories - always read the local template
- •Be thorough but concise - descriptions should be scannable
- •Focus on the "why" as much as the "what"
- •Include any breaking changes or migration notes prominently
- •If the PR touches multiple components, organize the description accordingly
- •Always attempt to run verification commands when possible
- •Clearly communicate which verification steps need manual testing