# PR Description Generator

> **Purpose:** Transform a branch's commits and diff into a complete, structured GitHub Pull Request description. Covers: what changed and why, how to test it, what could break, and any migration steps. Eliminates blank or lazy PRs — every PR tells the full story.

---

## Invocation

```
/pr-description [branch]
```

Internally collects:
```bash
git log origin/main..HEAD --oneline --no-merges
git diff origin/main...HEAD --stat
git diff origin/main...HEAD -- '*.sql'  # migration files
```

If no branch specified, uses current branch vs `main`/`master`.

---

## Analysis

### What to detect automatically

- **New routes or API endpoints** → flag in Test Plan
- **Database migrations** (any `.sql` files changed) → add Migration Steps section
- **Environment variable changes** (`.env.example` changes) → list new vars required
- **Breaking changes** (deleted exports, changed function signatures) → add Breaking Changes section
- **Test files changed or missing** → note in Test Plan

---

## Output: PR Description

```markdown
## Summary

[2-3 sentences: what this PR does and why it exists. Focus on the "why", not just the "what".]

**Type:** `feature` / `fix` / `refactor` / `chore` / `breaking`

---

## Changes

### [Area 1 — e.g., API]
- [What changed and why]
- [What changed and why]

### [Area 2 — e.g., Database]
- [What changed and why]

---

## Test Plan

- [ ] [Manual step 1 — e.g., "Log in as a new user and complete checkout"]
- [ ] [Manual step 2]
- [ ] All unit tests pass: `[test command]`
- [ ] [E2E scenario if applicable]

---

## Migration Steps

> Only include if there are database migrations or env var changes

1. Run migration: `[migration command]`
2. Add env vars: `VAR_NAME=...` (see `.env.example`)
3. Clear cache: `[cache clear command if needed]`

---

## Risk Assessment

| Risk | Likelihood | Mitigation |
|------|------------|------------|
| [e.g., Auth flow broken] | Low | Covered by E2E tests |
| [e.g., DB migration lock on large table] | Medium | Run during low-traffic window |

**Breaking changes:** [Yes/No — if Yes, list what callers need to update]

---

## Screenshots / Demo

[Note: Add before/after screenshots for UI changes]
```

---

## Rules

- Summary section is always first and always 2-3 sentences — never a list
- Migration Steps section: only include if `.sql` files or `.env.example` changed
- Risk Assessment: must have at least one row even if it's "No significant risks identified"
- Breaking Changes: explicitly state "None" if there are none — don't omit the section
- Test Plan must have at least 2 items: at least one manual step + one automated check
- Never write "See code" as a change description — describe the actual change in plain English