Skip to content

PierceS1/PS1 / .claude/skills/pr-description

pr-description

Verified

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*
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall