create-pr

What this skill does

# Create Pull Request Skill

When creating a pull request, follow this structured process. A good PR tells reviewers what changed, why, and how to verify it.

## 1. Pre-PR Discovery

Before creating the PR, gather context:

### Current Branch & Changes
```bash
# Current branch name
git branch --show-current

# Base branch (what we're merging into)
git log --oneline --decorate --first-parent HEAD | head -1
git remote show origin | grep "HEAD branch" | sed 's/.*: //'

# Commits on this branch (not on main/develop)
BASE_BRANCH=$(git remote show origin | grep "HEAD branch" | sed 's/.*: //')
git log --oneline ${BASE_BRANCH}..HEAD

# Files changed
git diff --name-status ${BASE_BRANCH}..HEAD

# Diff stats
git diff --stat ${BASE_BRANCH}..HEAD

# Full diff (for analysis)
git diff ${BASE_BRANCH}..HEAD
```

### Related Context
```bash
# Check for linked issues in commit messages
git log ${BASE_BRANCH}..HEAD --format="%B" | grep -iE "#[0-9]+|JIRA-[0-9]+|[A-Z]+-[0-9]+"

# Check for ticket references in branch name
git branch --show-current | grep -oE "[A-Z]+-[0-9]+|[0-9]+"

# Recent PR template
cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null
cat .github/pull_request_template.md 2>/dev/null
cat .gitlab/merge_request_templates/Default.md 2>/dev/null
cat docs/pull_request_template.md 2>/dev/null
```

## 2. Pre-PR Checks

Run automated checks before creating the PR:

### Code Quality
```bash
# Lint
npm run lint 2>/dev/null || yarn lint 2>/dev/null || pnpm lint 2>/dev/null
python -m flake8 2>/dev/null || python -m ruff check . 2>/dev/null
go vet ./... 2>/dev/null
bundle exec rubocop 2>/dev/null

# Format check
npx prettier --check . 2>/dev/null
python -m black --check . 2>/dev/null
gofmt -l . 2>/dev/null
```

### Tests
```bash
# Run tests
npm test 2>/dev/null || yarn test 2>/dev/null
python -m pytest 2>/dev/null
go test ./... 2>/dev/null
bundle exec rspec 2>/dev/null
php artisan test 2>/dev/null
cargo test 2>/dev/null
```

### Build
```bash
# Verify build succeeds
npm run build 2>/dev/null || yarn build 2>/dev/null
go build ./... 2>/dev/null
cargo build 2>/dev/null
```

### Type Check
```bash
# TypeScript
npx tsc --noEmit 2>/dev/null

# Python
python -m mypy . 2>/dev/null || python -m pyright 2>/dev/null
```

### Report Pre-Check Results
```
Pre-PR Checks:
✅ Lint — passed
✅ Tests — 142 passed, 0 failed
✅ Build — succeeded
✅ Type check — no errors
⚠️ Format — 2 files need formatting (auto-fix available)
❌ Test — 3 tests failing (must fix before PR)
```

If any critical checks fail, report them and suggest fixes BEFORE creating the PR.

## 3. Generate PR Title

### Title Format

Follow conventional commit style adapted for PR titles:
```
<type>(<scope>): <short description>
```

**Types:**
| Type | Use When |
|------|----------|
| `feat` | New feature or functionality |
| `fix` | Bug fix |
| `refactor` | Code restructuring without behavior change |
| `perf` | Performance improvement |
| `docs` | Documentation only |
| `test` | Adding or updating tests |
| `chore` | Build, CI, dependency updates |
| `style` | Formatting, whitespace, semicolons |
| `security` | Security fix or improvement |
| `breaking` | Breaking API or behavior change |

**Scope:** The module, component, or area affected.

**Examples:**
```
feat(auth): add OAuth2 login with Google and GitHub
fix(orders): prevent duplicate charges on retry
refactor(api): extract validation middleware from route handlers
perf(search): add Redis caching for product queries
docs(api): add OpenAPI specs for user endpoints
test(payments): add integration tests for refund flow
chore(deps): upgrade Next.js to 15.1 and React to 19
security(auth): fix JWT token validation bypass
```

### Title Rules
- Max 72 characters
- Imperative mood ("add" not "added" or "adding")
- No period at the end
- Lowercase after the colon
- Specific — not "fix bug" or "update code"

## 4. Generate PR Body

### Standard PR Body Template
```markdown
## What

[1-3 sentences explaining what this PR does. Be specific about the change, not just the area.]

## Why

[Explain the motivation. Link to the issue/ticket. What problem does this solve? What user need does it address?]

## How

[Brief technical explanation of the approach. What design decisions were made and why?]

## Changes

[Group changes by area/purpose]

### [Area 1, e.g., "API Changes"]
- Description of change 1
- Description of change 2

### [Area 2, e.g., "Database"]
- Description of change 3

### [Area 3, e.g., "Frontend"]
- Description of change 4

## Testing

[How was this tested? What should reviewers verify?]

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed
- [ ] Edge cases covered

### How to Test Manually
1. Step-by-step instructions
2. For reviewers to verify
3. The changes work correctly

## Screenshots / Recordings

[If UI changes, include before/after screenshots or recordings]

| Before | After |
|--------|-------|
| [screenshot] | [screenshot] |

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-reviewed my own code
- [ ] Added/updated documentation
- [ ] Added/updated tests
- [ ] No new warnings or errors
- [ ] Database migrations are reversible
- [ ] Breaking changes are documented

## Related

- Closes #[issue-number]
- Related to #[issue-number]
- Depends on #[pr-number]
- [Link to design doc / ADR / Figma]
```

### Adapt Body Based on Change Type

#### Bug Fix PR
```markdown
## What

Fixes [specific bug description] that caused [specific symptom].

## Root Cause

[Explain what was causing the bug]

## Fix

[Explain the fix and why this approach was chosen]

## How to Reproduce (Before Fix)

1. Step to reproduce
2. Step to reproduce
3. Observe: [wrong behavior]

## After Fix

1. Same steps
2. Same steps
3. Observe: [correct behavior]

## Regression Risk

[What could this fix break? What areas should be tested?]
```

#### Feature PR
```markdown
## What

Adds [feature name] that allows users to [capability].

## User Story

As a [role], I want to [action] so that [benefit].

## Implementation

[Technical approach, architecture decisions, trade-offs]

## API Changes (if applicable)

### New Endpoints
- `POST /api/[resource]` — [description]
- `GET /api/[resource]/:id` — [description]

### Request/Response Examples
[Include curl examples or request/response bodies]

## Database Changes (if applicable)

### New Tables/Columns
- `table_name.column_name` — [type] — [purpose]

### Migration
- Up: [what the migration does]
- Down: [how to rollback]

## Feature Flag

[Is this behind a feature flag? How to enable/disable?]

## Follow-up Work

- [ ] [Future task 1]
- [ ] [Future task 2]
```

#### Refactor PR
```markdown
## What

Refactors [area] to [improvement].

## Motivation

[Why now? What problem was the old code causing?]

## What Changed

[Structural changes, moved files, renamed things, new patterns]

## What Did NOT Change

[Explicitly state that behavior is unchanged. This reassures reviewers.]

## Verification

[How can reviewers confirm behavior is preserved?]
- All existing tests pass without modification
- [Additional verification steps]
```

#### Dependency Update PR
```markdown
## What

Upgrades [package] from [old version] to [new version].

## Why

[Security fix / new features needed / maintenance / EOL]

## Breaking Changes

[List any breaking changes from the upgrade and how they were handled]

## Changelog Highlights

- [Key change 1 from package changelog]
- [Key change 2]

## Migration Steps Taken

- [Step 1]
- [Step 2]
```

#### Database Migration PR
```markdown
## What

Adds/modifies [table/column/index] to support [feature/fix].

## Schema Changes

### Up Migration
[Describe what the migration does]

### Down Migration
[Describe rollback steps — must be reversible]

## Data Impact

- **Existing rows affected**: [count or estimate]
- **Backfill required**: [yes/no, if yes describe the backfill]
- **Downtime required**: [yes/no]
- **Estimated migration time**: [duration for production data