Pr Description

PR Description

A reviewer should be able to answer "what changed and why" in 30 seconds. That's the whole goal.

When to use

• "Write a PR description for this branch"
• "Summarize what's in this PR"
• "Fill out the PR template"
• "Draft a pull request"

Procedure

1. Identify the change set. Default to git diff ...HEAD where ` is the merge target (usually main / master / develop`).

``bash git fetch origin BASE=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main) git log --oneline "origin/$BASE..HEAD" git diff --stat "origin/$BASE...HEAD" ``

1. Look for an existing template. Check .github/pull_request_template.md or docs/PULL_REQUEST_TEMPLATE.md. If found, follow its structure; otherwise use the default below.

1. Read the diff itself, not just commit messages. Commit messages lie or lag; the diff is truth.

1. Identify:

• The one sentence that summarizes the change (this is the PR title)
• The why — problem, context, motivation
• The what — what actually changed, grouped logically (not file-by-file)
• Anything reviewer-visible: API changes, migrations, env vars, breaking changes
• Verification steps the reviewer can run

1. Draft. Then trim. First draft is always too long. Cut anything the diff already shows.

Default template

## Summary

## Why

Closes: #123

## Changes
- 
- 
- 

## How to verify
1. 
2. 

## Notes for reviewer

## Risk & rollout

Drop sections that don't apply. A docs PR doesn't need "Risk & rollout."

Title

(): if the project uses Conventional Commits, otherwise a clear imperative sentence ≤72 chars. No trailing period.

✅ feat(auth): support passwordless email login ✅ Fix race condition in cache invalidation ❌ Updates ❌ WIP - some changes to auth

Anti-patterns

• ❌ Listing files changed — the diff already does that
• ❌ "Various fixes and improvements" — useless to reviewer and to future archaeology
• ❌ Copy-pasting commit messages as the body
• ❌ Hiding breaking changes in the middle of a bullet list
• ❌ "Tested locally ✅" without saying what was tested
• ❌ Putting the "why" only in a linked issue — the reviewer should not need to context-switch

Tips

• Screenshots / before-after are gold for UI changes
• Migration notes: if a consumer needs to do something, put it in its own section with a ⚠️ so it can't be missed
• Stacked PRs: link to the parent and explicitly say "depends on #N"
• Draft PRs: prefix the summary with what's still TODO before review is welcome
• If the PR ended up doing more than one thing, suggest splitting before writing the description — it'll be a better PR

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kwhorne
• Source: kwhorne/elyra-skills
• License: MIT
• Homepage: https://elyracode.com

Install and usage instructions live in the source repository linked above.