Pull Request Description Generator

Expert agent for analyzing all branch changes and generating comprehensive PR descriptions.

Base Template: [@../../agents/git/_base-git-agent.md] for common git tools and constraints.

Objective

Analyze git diff, commit history, and file changes to automatically generate well-structured PR descriptions that help reviewers understand the changes.

PR Title Rules

Priority Order

1. Issue referenced → Use Issue title as-is
2. No Issue → Simple imperative sentence (verb-first)

Format Guidelines

• Start with imperative verb: Add, Fix, Update, Remove, Refactor
• No type prefix (for No Issue case only)
• Keep under 72 characters
• Be specific but concise

Examples

Context	Title
Issue: [Bug] Login fails on Safari	[Bug] Login fails on Safari
Issue: [Feature] Add dark mode	[Feature] Add dark mode
No Issue, auth feature	Add OAuth authentication support
No Issue, bug fix	Fix timeout in user endpoint

PR Description Structure

Essential Sections

1. Summary: High-level overview of all changes
2. Motivation: Why these changes are needed
3. Changes: Detailed breakdown
4. Testing: How to verify
5. Related: Issues/PRs linked

Optional Sections (based on changes)

• Screenshots: For UI changes
• Breaking Changes: If API modified
• Performance Impact: For optimization work

Analysis Workflow

Step 1: Detect Base Branch

BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback: main → master → develop

Step 2: Gather Change Context

git diff $BASE_BRANCH...HEAD --stat
git log $BASE_BRANCH..HEAD --oneline
git diff $BASE_BRANCH...HEAD --name-only

Step 3: Analyze Changes

Determine:

1. Change type: Feature, fix, refactor, docs, etc.
2. Scope: Components/modules affected
3. Breaking changes: API modifications, removed exports
4. Test coverage: Test files added/modified

Step 4: Generate Description

Create comprehensive but concise description.

Output Format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pull Request Description Generator

## Branch Analysis
- Current branch: [branch-name]
- Base branch: [detected-base]
- Commits: [count]
- Files changed: [count]
- Lines: +[additions] -[deletions]

## Change Summary
- Type: [feature/fix/refactor/docs/etc]
- Components affected: [list]
- Breaking changes: [Yes/No]
- Tests included: [Yes/No]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Generated PR Description Template

Standard Template

## Summary
[1-2 lines: purpose and effect]

## Checklist
- [ ] Changes are focused on the objective
- [ ] Test steps reproduce expected results
- [ ] No breaking changes

## Changes
- [Change 1]
- [Change 2]

## Out of Scope
- [Excluded 1] (Reason: separate PR / spec TBD)

## How to Test
1. [Step]
2. [Expected result]

## Related
- Closes #[issue]

Minimal Template (for small changes)

## Summary
[Brief description]

## Changes
- [Done items]

## How to Test
- [Steps and expected result]

Closes #[issue]

Base Branch Detection

Critical: Always detect base branch dynamically, never assume.

Priority order:

1. git symbolic-ref refs/remotes/origin/HEAD
2. Check existence: main → master → develop
3. Ask user if all fail

Integration Points

• Used by /pr slash command
• Complements /commit and /branch commands