PR Description Generator

Generate clear, comprehensive pull request descriptions that help reviewers quickly understand your changes.

Overview

This skill analyzes code changes and generates structured PR descriptions with two key sections:

• Why I'm Doing This: Business context, technical motivation, and background
• What I'm Doing: Implementation details, technical decisions, risks, and review focus areas

Workflow

Step 1: Gather Code Changes

Choose the appropriate method based on user input:

Method A: Analyze Current Branch (Default)

• Run git status to check current branch
• Run git diff $(git merge-base HEAD main)...HEAD to get all changes since branch diverged
• Run git log $(git merge-base HEAD main)..HEAD --oneline to see commit history

Method B: User-Specified Files

• If user mentions specific files, read those files
• Compare with git diff for those specific paths if needed

Step 2: Understand the Changes

Analyze the code changes to understand:

1. Purpose: What problem is being solved? What feature is being added?
2. Scope: Which files/modules are affected? How significant are the changes?
3. Type: Is this a feature, bug fix, refactoring, optimization, or something else?
4. Impact: What are the functional changes? Any performance implications?
5. Risks: Breaking changes, edge cases, deployment considerations?

Analysis Tips:

• Look at file names and paths to understand affected modules
• Read commit messages for context
• Identify patterns: new files (feature), modified logic (bug fix), restructured code (refactoring)
• Check for configuration changes, database migrations, API changes
• Note any TODO comments or follow-up work mentioned

Step 3: Generate the PR Description

Create a structured Markdown description with these sections:

Why I'm Doing This

Provide context that helps reviewers understand the motivation:

• Business problem or user need being addressed
• Technical motivation (performance, security, maintainability, tech debt)
• Reference to related issues, tickets, or discussions
• Background information for those unfamiliar with the context

Keep it concise but informative - 2-4 sentences or bullet points typically suffice.

What I'm Doing

Describe the implementation in a way that aids review:

High-level summary (required):

• Brief overview of the changes (1-2 sentences)
• Key components or files modified

Technical details (include when relevant):

• Important technical decisions and trade-offs
• New features or capabilities added
• Performance optimizations or improvements
• Architecture or design pattern changes
• Dependencies added or updated

Testing and validation (include when relevant):

• Test coverage added
• How changes were validated
• Edge cases handled

Risks and considerations (include when present):

• Breaking changes or deprecations
• Known limitations or edge cases
• Follow-up work needed
• Deployment considerations
• Areas requiring special review attention

Format Guidelines:

• Use bullet points for readability
• Group related changes together
• Highlight important information with bold
• Use code formatting for technical terms: function_name, file.ts
• Keep it scannable - reviewers should grasp key points quickly

Step 4: Review and Refine

Before presenting the PR description:

• Ensure "Why" section provides sufficient context
• Verify "What" section accurately reflects the code changes
• Check that risks and important considerations are called out
• Confirm the description helps reviewers know what to focus on

Output Format

Present the generated PR description in a Markdown code block so the user can easily copy it:

## Why I'm Doing This

[Context and motivation]

## What I'm Doing

[Implementation details]

**Technical Details:**
- [Key technical points]

**Risks:**
- [Any risks or considerations]

Best Practices

1. Be thorough but concise: Include all relevant information without overwhelming reviewers
2. Think like a reviewer: What would help someone understand and review these changes?
3. Call out the important stuff: Highlight breaking changes, risks, and areas needing careful review
4. Provide context: Don't assume reviewers have full background knowledge
5. Be honest about limitations: Note known issues, follow-up work, or trade-offs made

Examples and Reference

For detailed examples of well-written PR descriptions across different scenarios (features, bug fixes, optimizations, refactoring), see pr_examples.md.

Load this reference when you need inspiration or want to understand best practices for specific types of changes.