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