pr-description-generator

name	pr-description-generator
description	Generate comprehensive PR titles and descriptions with summary, test plan, risks, and linked issues. Use when the user asks to write or improve a pull request description.

Skill: PR Description Generator

Analyze branch changes and produce a complete pull request title and description following team conventions.

Trigger

When the user asks to generate, write, or improve a PR description — or when opening a new pull request.

Prerequisites

• Working on a feature/fix branch (not main or develop)
• Commits exist on the branch
• Base branch identified (default: main)

Steps

Step 1: Gather Branch Context

• Get current branch: git branch --show-current
• Get base branch (ask user or default to main)
• Get commit log: git log --oneline $(git merge-base HEAD origin/main)..HEAD
• Get file summary: git diff --stat origin/main...HEAD
• Get full diff summary: git diff origin/main...HEAD --stat
• Count changes: files changed, insertions, deletions

Step 2: Analyze Change Scope

• Identify the primary change category (feature, fix, refactor, docs, chore)
• List all affected modules/packages
• Identify breaking changes
• Identify database migrations
• Identify new dependencies
• Note any security-relevant changes (auth, permissions, input validation)

Step 3: Generate PR Title

• Format: imperative mood, 50–72 characters
• Mirror the primary commit or user-facing outcome
• Prefix with type if team convention: feat: ..., fix: ...
• For draft PRs, prefix with [WIP] or [Draft]

Step 4: Generate PR Body

Summary Section

• 2–4 sentences explaining what changed and why
• Link to design doc, RFC, or ticket if applicable

Type of Change

• Classify: feature / bug fix / docs / refactor / chore / breaking change
• Use checkboxes if PR template supports it

Changes Made

• Bullet list of key changes (grouped by module if multi-module)
• Mention new files, deleted files, renamed files
• Highlight architectural decisions

Testing

• List what was tested: unit, integration, manual
• Note what was not tested and why
• Include commands to reproduce: npm test -- --grep "feature-name"
• Mention if type-check and lint pass

Risk & Rollback

• Breaking changes and migration steps
• Feature flags used
• Rollback strategy (revert commit, feature flag toggle)
• Performance implications

Screenshots / Recordings

• Include placeholder section for UI changes
• Before/after screenshots when relevant

Checklist

• Tests added/updated
• Documentation updated
• No secrets or PII in code
• Type-check passes
• Lint passes
• Breaking changes documented

Related Issues

• Closes #123 for issues this PR resolves
• Refs #456 for related issues
• Link to parent epic or project board

Step 5: Security Review

• Verify no secrets, internal hostnames, or PII in the PR description
• Verify no internal URLs or resource ARNs
• Use generic placeholders where needed

Step 6: Output

• Present title and body in a copyable format
• Optionally provide a shorter version for stacked PRs
• Suggest reviewers based on changed files (if CODEOWNERS exists)

Rules

• NEVER include secrets, API keys, or real infrastructure names in PR text
• NEVER include PII (customer names, emails, etc.)
• ALWAYS mention what testing was done and what was skipped
• ALWAYS flag breaking changes prominently
• Keep the summary concise — reviewers skim first, read details second

Template Output

## Summary
Brief description of changes and motivation.

## Type of Change
- [ ] Feature
- [ ] Bug fix
- [ ] Refactor
- [ ] Documentation
- [ ] Breaking change

## Changes
- Added X to handle Y
- Updated Z for better performance
- Removed deprecated W

## Testing
- [x] Unit tests added for new service
- [x] Type-check passes
- [ ] Integration tests (not applicable — no API changes)

## Risk & Rollback
- Low risk — additive change behind feature flag
- Rollback: disable `FEATURE_X` flag

## Screenshots
N/A (backend only)

## Checklist
- [x] Tests added
- [x] Docs updated
- [x] No secrets in code
- [x] Type-check passes

## Related Issues
Closes #123
Refs #100

Completion

Copy-paste ready PR title and description. If the branch has many commits spanning multiple concerns, suggest splitting into stacked PRs.

If a Step Fails

• No commits on branch: Ask the user to describe planned changes
• Can't determine base branch: Default to main, ask for confirmation
• Large diff (>50 files): Group changes by module, provide high-level summary
• No test info: Add a note: "Testing plan TBD" and flag for the user