Comprehensive PR Description Creator
Create thorough PR descriptions that document EVERY meaningful change, not just the headline feature.
Phase 1: Complete Change Inventory
Determine the PR's base branch, then review the full diff, changed files, and all commits since branching.
NEVER assume you know what's in the PR based on branch name or first glance. PRs often contain secondary bug fixes, performance optimizations, test infrastructure improvements, documentation updates, dependency changes, and configuration adjustments alongside the main feature.
Phase 2: Categorize Changes
Using the diff output, create a categorized inventory of EVERY changed file:
| Category |
What to look for |
| Core application |
New methods, refactoring, bug fixes, performance improvements |
| Bug fixes |
Scan commit messages for "fix", "bug", "correct", "resolve" |
| Infrastructure |
Interceptors, middleware, base classes, test fixtures |
| Configuration |
Config files, constants, environment settings, package files |
| Tests |
New test files vs modified, test patterns, coverage improvements |
| Documentation |
README, docs folders, inline documentation |
| Build & tooling |
package.json, build configs, CI/CD, scripts |
| UI/Frontend |
Components, styles, state management |
For each commit, identify the category (feature, bugfix, test, docs, refactor, perf, chore) and understand WHY the change was made, not just WHAT changed.
Phase 3: Write Comprehensive Summary
Structure the PR description to cover all categories:
## Summary
[One sentence covering the MAIN change, plus brief mention of other significant improvements]
## User Impact
**[Main Feature Category]:**
- [Specific user-facing improvements]
**[Secondary Categories if applicable — e.g., Reliability, Performance]:**
- [Bug fixes with impact]
- [Performance improvements]
## Technical Notes
### 1. [Main Feature Name]
[Detailed explanation with file references]
### 2. [Bug Fixes / Corrections]
[Each bug fix: location, what was wrong, impact, fix]
### 3. [Infrastructure / Performance]
[Test improvements, framework changes, optimizations]
### 4. [Configuration & Dependencies]
[Constants, config changes, dependency updates]
### 5. [Documentation]
[README updates, new docs, removed obsolete content]
## Testing
[Comprehensive test results with specific numbers]
## Implementation Approach
[List ALL commits with brief explanation of each]
---
Generated with [Claude Code](https://claude.com/claude-code)
Phase 4: Update the PR
Show the summary to the user and ask if they want to update the PR. Only update with gh pr edit after approval.
Quality Checklist
Before finalizing, verify:
- Completeness: Every commit is represented in the summary
- Accuracy: All bug fixes are documented with impact
- Context: WHY changes were made, not just WHAT changed
- Organization: Changes grouped logically
- Specificity: File paths for critical changes
- Impact: User-facing vs internal changes clearly separated
- Testing: Actual test results reported, not assumptions
Gotchas
- PRs often contain a week's worth of work across multiple areas. The biggest mistake is focusing only on the main feature and skipping "small" changes like constants, config, docs, and especially bug fixes.
- If no PR exists yet, create one first before running the update process.
- Shell constructs like
$(), &&, and variable assignments in Bash calls can trigger permission prompts. Prefer simple, single-command calls when possible.
1---2name: update-pr3description: Creates comprehensive PR descriptions by systematically reviewing ALL changes - features, bug fixes, tests, docs, and infrastructure. Use when user asks to "update the PR", "prepare PR for review", "write PR description", or "document branch changes". Requires gh CLI.4---56# Comprehensive PR Description Creator78Create thorough PR descriptions that document EVERY meaningful change, not just the headline feature.910## Phase 1: Complete Change Inventory1112Determine the PR's base branch, then review the full diff, changed files, and all commits since branching.1314**NEVER assume you know what's in the PR based on branch name or first glance.** PRs often contain secondary bug fixes, performance optimizations, test infrastructure improvements, documentation updates, dependency changes, and configuration adjustments alongside the main feature.1516## Phase 2: Categorize Changes1718Using the diff output, create a categorized inventory of EVERY changed file:1920| Category | What to look for |21|----------|-----------------|22| **Core application** | New methods, refactoring, bug fixes, performance improvements |23| **Bug fixes** | Scan commit messages for "fix", "bug", "correct", "resolve" |24| **Infrastructure** | Interceptors, middleware, base classes, test fixtures |25| **Configuration** | Config files, constants, environment settings, package files |26| **Tests** | New test files vs modified, test patterns, coverage improvements |27| **Documentation** | README, docs folders, inline documentation |28| **Build & tooling** | package.json, build configs, CI/CD, scripts |29| **UI/Frontend** | Components, styles, state management |3031For each commit, identify the category (feature, bugfix, test, docs, refactor, perf, chore) and understand WHY the change was made, not just WHAT changed.3233## Phase 3: Write Comprehensive Summary3435Structure the PR description to cover all categories:3637```markdown38## Summary3940[One sentence covering the MAIN change, plus brief mention of other significant improvements]4142## User Impact4344**[Main Feature Category]:**45- [Specific user-facing improvements]4647**[Secondary Categories if applicable — e.g., Reliability, Performance]:**48- [Bug fixes with impact]49- [Performance improvements]5051## Technical Notes5253### 1. [Main Feature Name]54[Detailed explanation with file references]5556### 2. [Bug Fixes / Corrections]57[Each bug fix: location, what was wrong, impact, fix]5859### 3. [Infrastructure / Performance]60[Test improvements, framework changes, optimizations]6162### 4. [Configuration & Dependencies]63[Constants, config changes, dependency updates]6465### 5. [Documentation]66[README updates, new docs, removed obsolete content]6768## Testing6970[Comprehensive test results with specific numbers]7172## Implementation Approach7374[List ALL commits with brief explanation of each]7576---7778Generated with [Claude Code](https://claude.com/claude-code)79```8081## Phase 4: Update the PR8283Show the summary to the user and ask if they want to update the PR. Only update with `gh pr edit` after approval.8485## Quality Checklist8687Before finalizing, verify:8889- **Completeness**: Every commit is represented in the summary90- **Accuracy**: All bug fixes are documented with impact91- **Context**: WHY changes were made, not just WHAT changed92- **Organization**: Changes grouped logically93- **Specificity**: File paths for critical changes94- **Impact**: User-facing vs internal changes clearly separated95- **Testing**: Actual test results reported, not assumptions9697## Gotchas9899- PRs often contain a week's worth of work across multiple areas. The biggest mistake is focusing only on the main feature and skipping "small" changes like constants, config, docs, and especially bug fixes.100- If no PR exists yet, create one first before running the update process.101- Shell constructs like `$()`, `&&`, and variable assignments in Bash calls can trigger permission prompts. Prefer simple, single-command calls when possible.
propstreet