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.