pr-description

PR Description Skill

This skill provides a structured approach to creating comprehensive pull request descriptions that help reviewers understand changes quickly.

When to Use

Use this skill when:

• Creating a new pull request
• User asks to "create a PR description" or "write a PR description"
• Documenting significant code changes for review

File Creation (Optional)

If saving the PR description to a file:

• Pattern: pr_description_<descriptive_title>_<timestamp>.md
• Get timestamp: date +"%Y%m%d_%H%M%S"
• Example: pr_description_user_auth_refactor_20250612_152832.md

Required Structure

# PR Title: [Descriptive Title]

## 📋 Summary
Brief overview of what this PR accomplishes in 2-3 sentences.

## 📊 Data Flow Diagram
[Mermaid diagram showing the flow/architecture - use `mermaid` skill for styling]

## 🗂️ Entity Relationship Diagram
[Include if creating/modifying data relationships - Mermaid ERD]

## 🎯 Goals
- Primary objective 1
- Primary objective 2
- Any secondary objectives

## 🔍 Changes in this PR
- Description of key changes
- Any config file changes
- Schema modifications
- Breaking changes (if any)

## 🧪 Testing
### Commands Run
```bash
# List exact commands used for testing
npm test
npm run lint

Results

• ✅ All tests passed
• ✅ Linting passed
• ✅ Build successful
• Include any relevant screenshots or output

Validation

• Key scenarios tested
• Edge cases covered
• Performance considerations

📋 Notes for Reviewers

• Pay attention to: [specific areas]
• Assumptions made: [list any assumptions]
• Dependencies: [any upstream/downstream impacts]

🔜 Future Work

• Any follow-up tasks not included in this PR
• Potential optimisations
• Additional testing needed

## Mermaid Diagrams

**Use the `mermaid` skill** for diagram syntax and styling that works in both light and dark mode.

### Data Flow Diagram
Show the complete flow of data or logic:
- Input sources
- Processing steps
- Output destinations
- Include a colour-coded legend

### Entity Relationship Diagram (When Applicable)
Show object/data relationships:
- Primary keys (PK)
- Foreign keys (FK)
- Relationship cardinality (one-to-many, many-to-many)

## Content Guidelines

### Summary Section
- Explain business context briefly
- Highlight key benefits
- Keep it to 2-3 sentences

### Changes Section
- Focus on what matters to reviewers
- Group related changes together
- Note any breaking changes prominently

### Testing Section
- **ALWAYS include exact commands run**
- Show evidence of successful tests
- Include validation results
- Add screenshots when helpful

### Future Work Section
- List intentionally deferred items
- Suggest optimisations or enhancements
- Note any technical debt created

## Key Principles

1. **Be specific**: Include exact commands, concrete examples
2. **Show evidence**: Screenshots, command outputs, test results
3. **Think reviewer-first**: What would a reviewer need to understand the changes?
4. **Business context**: Explain the "why" not just the "what"
5. **Keep it scannable**: Use headers, bullet points, and formatting

## Good Examples

### Good Summary
"This PR refactors the user authentication flow to use JWT tokens instead of session cookies. The change improves scalability for our microservices architecture and reduces server-side session storage requirements."

### Good Testing Description
```bash
# Commands run
npm run test:unit
npm run test:integration
npm run lint

Results:

• ✅ 47 unit tests passed
• ✅ 12 integration tests passed
• ✅ No linting errors
• ✅ Manual testing completed on staging environment

Error Handling

• If unable to determine scope of changes, ask user for clarification
• If testing hasn't been completed, remind user to run tests first
• If no diagrams provided, create placeholder diagrams and ask user to review