PR Description Generator

Git diff in, production-ready PR description out. Understands what changed, why it matters, and what reviewers need to know.

Procedure

1. Analyze the diff

Parse the git diff to extract:

• Files changed: group by type (source, tests, config, docs, migrations, CI)
• Change volume: additions, deletions, net lines per file
• Change types: new files, modified files, deleted files, renamed files
• Language breakdown: which languages are affected
• Key patterns detected:
  • New API endpoints (route definitions)
  • Database schema changes (migrations, model changes)
  • Dependency changes (lockfile modifications)
  • Configuration changes (env vars, feature flags)
  • Test additions/modifications
  • Breaking changes (removed exports, changed signatures, renamed fields)

2. Analyze commits (if provided)

Parse commit messages for:

• Conventional commit types (feat, fix, refactor, chore, docs, test, perf, ci)
• Scope information
• Breaking change markers (! or BREAKING CHANGE footer)
• Issue/ticket references (#123, JIRA-456)
• Co-authors

3. Determine change category

Classify the overall PR:

• Feature: new capability added
• Bug Fix: corrects incorrect behavior
• Refactor: restructures without behavior change
• Performance: improves speed/memory/efficiency
• Security: addresses vulnerability or hardens
• Infrastructure: CI/CD, build, deploy changes
• Documentation: docs-only changes
• Dependencies: updates/adds/removes packages
• Breaking Change: modifies public API/interface

4. Generate title

Format: <type>(<scope>): <concise description>

Rules:

• Max 72 characters
• Imperative mood ("Add", not "Added" or "Adds")
• No period at end
• Scope is the most affected module/component

Examples:

• feat(auth): add OAuth2 PKCE flow for mobile clients
• fix(api): prevent race condition in concurrent order processing
• refactor(db): migrate from raw SQL to query builder

5. Generate description body

Standard template:

## Summary

[1-3 sentence overview of what this PR does and why]

## Changes

### [Category 1: e.g., "API Changes"]
- [Specific change with context]
- [Specific change with context]

### [Category 2: e.g., "Database"]
- [Specific change with context]

## Motivation

[Why this change is needed. Link to issue/ticket if available.]

## Testing

- [ ] Unit tests added/updated for [specific area]
- [ ] Integration tests cover [specific scenario]
- [ ] Manual testing: [steps to verify]

## Review Notes

- **Start here**: `path/to/most-important-file.ts` — [why]
- **Key decision**: [explain non-obvious architectural choice]
- **Risk area**: [flag anything tricky or fragile]

## Screenshots / Examples

[If UI changes or API response changes, show before/after]

## Checklist

- [ ] Tests pass locally
- [ ] No new warnings introduced
- [ ] Documentation updated (if needed)
- [ ] Breaking changes documented (if any)

Minimal template:

## What

[1-2 sentences]

## Why

[1-2 sentences]

## Test plan

[How to verify]

Security template (adds):

## Security Impact

- **Threat model**: [what attack vector this addresses]
- **OWASP category**: [if applicable]
- **CVE reference**: [if fixing a known vulnerability]
- **Rollback plan**: [how to revert if issues found]

Breaking change template (adds):

## Breaking Changes

### What breaks
- [Specific breaking change]

### Migration guide
1. [Step to update consumers]
2. [Step to update consumers]

### Affected consumers
- [Service/library that depends on changed API]

6. Smart analysis

Apply these heuristics:

• If tests added/modified: note coverage impact
• If migration files: warn about rollback considerations
• If .env or config changes: flag deployment requirements
• If new dependencies: note what they do and why chosen
• If file renames: explain the naming convention change
• If large diff (>500 lines): suggest splitting and explain PR scope
• If only test files: note this is a test-only PR
• If API changes: highlight request/response shape changes

7. Output

{
  "title": "feat(auth): add OAuth2 PKCE flow for mobile clients",
  "body": "## Summary\n\n...",
  "labels": ["feature", "auth", "needs-review"],
  "reviewers_hint": ["@backend-team — API changes", "@security-team — auth flow"],
  "estimated_review_time": "15 min",
  "risk_level": "medium",
  "breaking": false,
  "deploy_notes": "Requires AUTH_PKCE_ENABLED=true env var"
}

Pitfalls

• Don't just list files changed — explain the purpose of each change
• Don't expose secrets or tokens that appear in diff (redact them)
• Large diffs (>1000 lines) should get a "consider splitting" note
• Renamed files show as delete+add — detect renames via similarity
• Binary file changes (images, compiled assets) need different handling
• Merge commits in the log add noise — filter them out
• Monorepo PRs may span multiple packages — organize by package
• Draft/WIP PRs should be flagged with remaining TODOs