John Ogle
7903b2dfd0
All checks were successful
CI / check (push) Successful in 3m16s
Correct terminology mismatch: - Rename skills/ to commands/ (these are user-invokable commands) - Create new skills/ for reference materials - Move bd_workflow.md to skills/ (it's reference material) - Add micro-skills and formulas directories - Update default.nix to install both commands and skills Commands → ~/.claude/commands/ (invokable as /command-name) Skills → ~/.claude/commands/skills/ (reference materials) Formulas → ~/.beads/formulas/ (workflow templates) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
69 lines
1.7 KiB
Markdown
69 lines
1.7 KiB
Markdown
---
|
|
description: How to write comprehensive PR descriptions that help reviewers understand changes
|
|
---
|
|
|
|
# PR Description
|
|
|
|
Write PR descriptions that help reviewers understand what changed and why.
|
|
|
|
## Structure
|
|
|
|
Use this standard structure for PR descriptions:
|
|
|
|
```markdown
|
|
## Summary
|
|
<1-3 bullet points of what changed and why>
|
|
|
|
## Context
|
|
<Why this change was needed - the problem being solved>
|
|
<Link to related issues/tickets>
|
|
|
|
## Changes
|
|
<Detailed breakdown by area/component>
|
|
- Area 1: What changed and why
|
|
- Area 2: What changed and why
|
|
|
|
## Testing
|
|
<How this was verified>
|
|
- Automated: Tests added/updated, CI status
|
|
- Manual: Steps to verify functionality
|
|
|
|
## Screenshots (if UI changes)
|
|
<Before/after screenshots if applicable>
|
|
```
|
|
|
|
## Guidelines
|
|
|
|
### Lead with WHY, not WHAT
|
|
- The diff shows WHAT changed - your description explains WHY
|
|
- Start with the problem being solved
|
|
- Explain the approach chosen and alternatives considered
|
|
|
|
### Link to context
|
|
- Reference related issues: `Fixes #123` or `Relates to #456`
|
|
- Link to design docs or discussions
|
|
- Mention dependent PRs if any
|
|
|
|
### Call out review areas
|
|
- Highlight areas needing careful review
|
|
- Note any tricky or non-obvious code
|
|
- Point out architectural decisions
|
|
|
|
### Note breaking changes prominently
|
|
- Use a dedicated "Breaking Changes" section if applicable
|
|
- Explain migration path for consumers
|
|
- List any deprecations
|
|
|
|
### Be scannable
|
|
- Use bullet points over paragraphs
|
|
- Keep sections focused and concise
|
|
- Put the most important info first
|
|
|
|
## Anti-patterns to Avoid
|
|
|
|
- Empty descriptions or just "fixes bug"
|
|
- Repeating the commit messages verbatim
|
|
- Including irrelevant implementation details
|
|
- Missing context on why the change was made
|
|
- Forgetting to mention breaking changes
|