| name | pr-description |
| description | Prepares a pull request description. Use when asked to write or draft a PR description. |
PR Description Style
Write PR descriptions following these conventions:
Title
- Imperative mood: "Add feature" not "Added feature"
- Capitalize the first letter
- Be descriptive; longer than commit subjects is fine
Body Structure
- Issue link (if applicable): Start or end with
Part of <url> or Fixes <url>
- Why: Explain WHY this change is needed - the problem, context, or motivation
- Assumptions: Call out any assumptions made or decisions that reviewers should know about
- Code references: Link directly to specific code when relevant (see below)
What NOT to do
- Don't write bullet points listing what you did (e.g., "- Updated X", "- Added Y", "- Fixed Z")
- Reviewers can see what changed in the diff; the description should explain WHY
Code References
When referencing code, use permanent links with the commit SHA, not main:
Good: https://github.com/shop/world/blob/845bb9d9e90c30668470d808593389397f4e89bd/path/to/file.rb#L691-L695
Bad: https://github.com/shop/world/blob/main/path/to/file.rb#L691-L695
This ensures links don't break when code moves after the PR merges.
Optional Sections
## Questions for reviewers - When you need input on specific decisions### Before / ### After - For visual changes, include screenshots<details><summary>...</summary>...</details> - For verbose info like stacktraces or long code samples- Links to related PRs when relevant
Example
Part of https://github.com/shop/issues-team/issues/123
When identity isn't running in development, the UserLimits field was returning "Field 'userLimits' doesn't exist" because visibility checks were failing.
The UserLimits type requires USER_ACCESS scope. Even though mock API scopes were being returned, the context had `user_access: false` because the mock token didn't have a `sub` claim. The fix adds the missing claim and corresponding context overrides.
I assumed we only need this for development mode - if we need similar behavior in test, we'd need to extend `TestContextOverrides` as well.
The key change is in [DevelopmentContextOverrides](https://github.com/shop/world/blob/a1b2c3d/path/to/file.rb#L45-L52) where we now check for the sub claim before setting user_access.
## Questions for reviewers
Should we add similar overrides for other scopes?
Output
- Run
ruby ~/.claude/skills/pr-description/context.rb to get branch name, main SHA, commits, and diff stats
- If the diff stats aren't enough context, run the full diff command printed at the end of the script output
- Write the PR description to
~/.claude/local-notes/pr-descriptions/pr-<branch_name>.md using GitHub flavored markdown
- Copy to clipboard:
cat ~/.claude/local-notes/pr-descriptions/pr-<branch_name>.md | pbcopy
- Tell the user it's been copied and mention the file path in case they need to retrieve it later
