pr-description

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*