| name | writing-pr-descriptions |
| description | Voice guide for writing PR descriptions. Use this skill for ALL PR creation and updates (via gh CLI or editing existing PRs). Contains your specific voice rules, anti-patterns, examples, and workflow. Never write PR descriptions without invoking this skill first. |
| allowed-tools | ["Bash","Read","Glob","Grep"] |
Writing PR Descriptions
⚡ QUICK START
- Check for project PR template:
.github/PULL_REQUEST_TEMPLATE.md
- Gather changes:
git log main..HEAD --oneline and git diff main...HEAD --stat
- Ask user for: Jira URL, Slack thread, screen recording (if UI)
- Draft using voice rules below
- Create PR:
gh pr create --draft --title "..." --body "..."
Voice Guide
Spirit
- Respect reviewer time - Get to the point, then stop
- User-centric framing - What problem does this solve for users?
- Show, don't tell - Screen recordings > paragraphs of text
- Practical validation - Teach reviewers like a tutorial
Conciseness Rules
- What section: Include every significant change theme - no cap. Could be 2 bullets, could be 8. Whatever fits the PR.
- Why section: 1-3 bullets (not a paragraph). Focus on user benefit.
- Validation: 10 steps MAX. Narrative "Expect to..." style.
Structure Requirements
- Start with
> [!NOTE] callout if PR depends on another PR
- Include 🍿 screen recording for ANY UI changes
- Mention deployment timing if backend/frontend coordination needed
- Link actual Jira/Slack (ask user if not provided)
Language Rules
- Concrete examples over jargon: "item with
_ separator" not "multi-entity composite perturbation"
- Frame "Why" around USER benefit, not technical constraints
- Validation reads like a tutorial: "Expect to see X"
What NOT to Do
❌ Checkbox-heavy validation sections
❌ Technical jargon when plain language works
❌ Listing every file changed
❌ Business rule explanations (put in code comments)
❌ "Comprehensive" descriptions - less is more
❌ Placeholder links - ask for real URLs
Scope Discipline
- Focus on the FEATURE users will see
- Omit implementation wiring (threading params, type updates)
- If it's not visible to users or reviewers, skip it
Template Handling
- Project template first - Use
.github/PULL_REQUEST_TEMPLATE.md as base
- Respect conventions - Match their emoji style (✅ not 💪)
- Enhance sparingly - Add sections only if project template is minimal
Example: Good PR Description
> [!NOTE]
> Builds on #142 to leverage its frontend helpers
## ✅ What
- Adds an "Include archived items" toggle to filter archived entries in/out of all views
- Includes a tooltip explaining what "archived items" are
- Hides the toggle completely if the current dataset doesn't have archived items
- Since this toggle won't appear until datasets with archived items are in prod, it's safe to deploy backend and frontend together
### 🍿 Screen recording of validation steps below
[video]
## 🤔 Why
- This dataset is the first appearance of archived items in the app
- While users gain an understanding of how to interpret these items, we want them to have the ability to hide them
## 👩🔬 How to validate
1. `./bin/dev.sh` + `cd frontend` + `npm start`
2. Expect to **not** see the "Include archived items" toggle
3. Select a dataset with archived items
4. Expect to see the toggle now
5. Query a few items, including one that's archived (look for the `[archived]` badge)
6. Expect to see the archived item in the list, detail view, and charts
7. Toggle archived items off
8. Expect the archived item's chip to be disabled
9. Expect the disabled item's tooltip to explain why
10. Expect the archived item to no longer appear in your views
## 🔖 Related links
- [Jira task](https://jira.example.com/browse/PROJ-123)
- [Slack thread](https://workspace.slack.com/archives/C12345/p1234567890)
Why This Works
✅ Dependency callout at top
✅ Screen recording before text
✅ Deployment timing mentioned
✅ User-centric Why
✅ Concrete language
✅ Narrative validation (10 steps)
✅ Real links (not placeholders)
PR Creation Commands
gh issue list --state open
gh pr create --draft --title "Title" --body "$(cat <<'EOF'
[PR body here]
EOF
)"
gh pr view --web
Process Checklist
