# Pr Description > Generate comprehensive pull request descriptions that help reviewers understand code changes. Use when the user asks to "generate PR description", "create PR summary", "write PR intro", or needs help documenting their code changes for review. Analyzes git diffs or specified files to create structured descriptions covering why changes were made and what was implemented. Use when this capability is needed. - Skill: `tomevault-io/pr-description-4` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/pr-description-4` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pr-description-4/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/pr-description-4 --- # 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: ```markdown ## 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](references/pr_examples.md). Load this reference when you need inspiration or want to understand best practices for specific types of changes. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/luohaha) — claim your Tome and manage your conversions.