name: describe-pr
description: Generate comprehensive PR descriptions following repository templates

Generate PR Description

You are tasked with generating a comprehensive pull request description following the repository's standard template.

Steps to follow:

1. Read the PR description template:
2. First, check if thoughts/shared/pr_description.md exists
3. If it doesn't exist, inform the user they need to create a PR description template at thoughts/shared/pr_description.md

4. Read the template carefully to understand all sections and requirements

5. Identify the PR to describe:

6. Check if the current branch has an associated PR: gh pr view --json url,number,title,state 2>/dev/null
7. 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

8. Ask the user which PR they want to describe

9. Check for existing description:

10. Check if thoughts/shared/prs/{number}_description.md already exists
11. If it exists, read it and inform the user you'll be updating it

12. Consider what has changed since the last description was written

13. Gather comprehensive PR information:

14. Get the full PR diff: gh pr diff {number}
15. If you get an error about no default remote repository, instruct the user to run gh repo set-default and select the appropriate repository
16. Get commit history: gh pr view {number} --json commits
17. Review the base branch: gh pr view {number} --json baseRefName
18. Get PR metadata: gh pr view {number} --json url,title,number,state

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_PROJECT_DIR/.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

1. Analyze the changes thoroughly: (ultrathink about the code changes, their architectural implications, and potential impacts)
2. Read through the entire diff carefully
3. For context, read any files that are referenced but not shown in the diff
4. Understand the purpose and impact of each change
5. Identify user-facing changes vs internal implementation details

6. Look for breaking changes or migration requirements

7. Handle verification requirements:

8. Look for any checklist items in the "How to verify it" section of the template
9. 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

10. Document any verification steps you couldn't complete

11. Generate the description:

12. 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
13. 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

14. Ensure all checklist items are addressed (checked or explained)

15. Save the description:

16. Write the completed description to thoughts/shared/prs/{number}_description.md

17. Show the user the generated description

18. Update the PR:

19. Update the PR description directly: gh pr edit {number} --body-file thoughts/shared/prs/{number}_description.md
20. Confirm the update was successful
21. If any verification steps remain unchecked, remind the user to complete them before merging

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