| name | pr-description |
| description | Use this skill when creating or updating PR descriptions. Provides detailed guidelines for writing clear, comprehensive pull request descriptions with proper Summary and Testing sections. |
PR Description
Write clear, comprehensive pull request descriptions following these guidelines.
PR Description Structure
Required Sections
Every PR must have:
## Summary
- Opening paragraph explaining the high-level goal and motivation
- Bullet points describing what specifically changed
- Keep it proportional: Small changes deserve concise descriptions; large changes deserve detailed breakdowns
- Focus on concrete details, not vague descriptions
- Use specific values, file paths, and configuration details
## Testing
- How changes were validated
- Commands run to verify correctness
- Manual testing performed
- Screenshots/videos for UI changes
Optional Sections (use when relevant)
## Key Changes - For complex PRs, break down changes by component, environment, or logical grouping
Technical Detail Sections:
- ## Deployment Considerations - Pre/post-deployment steps required
- ## Rationale - Explain design decisions and "why" questions
- ## Behavior - Describe how the system behaves after changes
- ## Migration - Steps to transition from old to new
- ## Configuration - New settings or environment variables
- ## Next Steps - Follow-up work or monitoring needed
Writing Guidelines
Summary Section
Match description length to change scope:
- Small, focused changes (1-3 files, simple logic) → 1 paragraph + 2-4 bullets max
- Medium changes (multiple components, some complexity) → 1 paragraph + grouped bullets
- Large changes (major refactoring, new systems) → Detailed breakdown with subsections
Opening paragraph:
- Explain what problem is solved or what feature is added
- Include the "why" — business value or technical motivation
- Keep it to 1-3 sentences
Bullet points:
- Be concise: Convey core meaning with minimal words
- Be specific with values, not vague descriptions
- Include inline code formatting: Use backticks for
fields, values, and file.paths
- Group related changes under bold headers only when there are multiple distinct logical sections
Testing Section
Document all validation performed with specific details:
- What commands were run
- What test coverage was added or modified
- What manual verification steps were taken
- Do NOT write vague statements like "Tested manually"
Style Guidelines
Use inline code formatting liberally for field names, values, file paths, and commands.
Use bold headers for subsections to make long descriptions scannable.
Be specific with numbers — quote actual values, not vague descriptions.
Explain trade-offs and decisions — show you considered alternatives.
Show before/after code snippets when relevant:
- Structural improvements, API changes, logic simplification, pattern migrations
- Do NOT include for large diffs, trivial changes, or new features from scratch
PR Footer
At the bottom of every PR description, include:
---
🤖 *Generated by Computer*
