PR Description Template Skill

This skill provides everything needed to write high-quality PR descriptions: templates, format specifications, and examples.

Quick Reference

Available Templates

Template Selection Guide

Choose feature when:

• Adding new functionality (greenfield development)
• Implementing new APIs, services, or components
• Adding new user-facing features
• Introducing new capabilities to the codebase

Choose bugfix when:

• Fixing a bug of any size
• Addressing regressions
• Hotfixes for production issues
• Correcting unexpected behavior

Choose refactor when:

• Making architectural changes
• Restructuring code without changing behavior
• Reorganizing modules or file structure
• Implementing breaking changes with migration
• Improving code quality without adding features

PR Description Format

Every PR description MUST follow this structure. This is the canonical format for all pull requests.

Required Sections

## Summary

<High-level summary of changes and context for why the changes were made.
Should answer: What does this PR do? Why is it needed?
Keep to 2-4 sentences. Focus on business value and user impact.>

## What's Included

<Compact list organized by category to help reviewer understand scope at a glance>

**Source Code:**
- `path/to/file.py` - Brief description of change

**Tests:**
- `tests/test_file.py` - What's being tested

**Documentation:**
- `docs/file.md` - What was documented (or note if missing)

**Configuration:**
- `pyproject.toml` - Dependencies added/changed

## Key Design Decisions

<Design decisions to document for reviewer context.
Focus on "why this approach" not implementation details.
Number each decision for easy reference in review comments.>

1. **Decision Title**: Rationale for why this approach was chosen over alternatives

2. **Convention Deviation** (if any): Any intentional deviations from development-conventions with justification

## Critical Areas for Review

<Prioritized areas deserving careful review.
Help reviewer focus their attention on what matters most.
Include line numbers when specific ranges need attention.>

1. **`path/to/critical/file.py:L10-L50`** - Description of why this needs careful review (e.g., complex logic, security implications, breaking change)

2. **`path/to/another/file.py`** - Why this is important to review

Optional Sections

Include these when applicable:

## Future Phases

<Only include if this PR is a partial implementation of a larger plan>

The following phases from the [implementation plan](<plan-path>) are planned for future PRs:
- **Phase N**: Brief description of what's coming
- **Phase M**: Brief description of what's coming

## Breaking Changes

<Only include if there are breaking changes>

- **Change**: Description of what breaks
- **Migration**: How to update dependent code
- **Deprecation Timeline**: When old behavior will be removed (if applicable)

## Testing Notes

<Only include if testing requires special setup or has important caveats>

- How to test locally
- Required environment setup
- Known edge cases

Writing Guidelines

Summary Section

DO:

• Start with what the PR accomplishes (the "what")
• Explain why it's needed (the "why")
• Mention user-facing impact if applicable
• Keep it concise (2-4 sentences)

DON'T:

• List files changed (that's for "What's Included")
• Include implementation details
• Use vague language like "various improvements"
• Make it longer than a short paragraph

Good Example:

Adds batch processing support for the data pipeline, enabling processing of up to 10,000 records in a single operation. This addresses the performance bottleneck reported in issue #123 where large datasets caused timeouts.

Bad Example:

This PR updates processor.py and adds tests. Made some improvements to the code.

What's Included Section

DO:

• Group by file type (Source, Tests, Documentation, Configuration)
• Use relative paths from repository root
• Keep descriptions to one line per file
• Highlight new files vs modified files if helpful

DON'T:

• Include every file if there are many (summarize: "15 test files for new validators")
• Add excessive detail (save that for design decisions)
• Forget to mention documentation updates (or note "Documentation: None" if appropriate)

Key Design Decisions Section

DO:

• Number decisions for easy reference in reviews
• Explain the "why" not the "what"
• Mention alternatives considered when relevant
• Flag any convention deviations with justification

DON'T:

• Repeat implementation details
• Include decisions that are obvious
• Skip this section (even simple PRs have at least one decision worth noting)

Critical Areas for Review Section

DO:

• Prioritize areas by importance
• Include line numbers for specific ranges
• Explain WHY each area needs attention
• Mention security, complexity, or breaking change concerns

DON'T:

• List every file (only truly critical areas)
• Be vague ("please review carefully")
• Skip this section (helps reviewers use their time effectively)

Title Guidelines

PR titles should be concise and descriptive:

Format: <type>: <brief description>

Types:

• feat: - New feature
• fix: - Bug fix
• refactor: - Code restructuring
• docs: - Documentation only
• test: - Test additions/changes
• chore: - Maintenance tasks

Good Examples:

• feat: Add batch processing for data pipeline
• fix: Resolve timeout on large dataset uploads
• refactor: Extract validation logic into separate module

Bad Examples:

• Update files (too vague)
• Fix bug (what bug?)
• WIP (not ready for review)

Action Instructions

Based on the argument provided, perform one of these actions:

/pr-description-template (no args) or /pr-description-template help

Show this overview with available templates and commands.

/pr-description-template feature

Read and display: .claude/skills/pr-description-template/example-feature.md

/pr-description-template bugfix

Read and display: .claude/skills/pr-description-template/example-bugfix.md

/pr-description-template refactor

Read and display: .claude/skills/pr-description-template/example-refactor.md

/pr-description-template format

Display the "PR Description Format" section from this skill.

Template File Locations

All example templates are in this skill directory:

• example-feature.md - Complete example for new feature PRs
• example-bugfix.md - Complete example for bug fix PRs
• example-refactor.md - Complete example for refactoring PRs