pr-creation

What this skill does

# PR Creation

This skill MUST be invoked whenever you are creating a pull request. It handles the complete workflow from context gathering to PR submission with consistent formatting.

## When This Skill Activates

**Auto-invoke this skill when the user implies a PR should be created:**

| Category | Trigger Phrases |
|----------|-----------------|
| **Explicit PR** | "create PR", "open PR", "make PR", "create a pull request" |
| **Review intent** | "ready for review", "review ready", "send for review" |
| **Push for PR** | "push for PR", "push and PR", "push and create PR" |
| **Submission** | "submit for review", "open pull request", "make a pull request" |

**Key insight:** If the user's intent results in `gh pr create` being run, this skill MUST be used first.

**Do NOT run `gh pr create` without this skill.**

## Complete PR Creation Workflow

### Step 1: Gather Context

```bash
git status                              # Check working tree state
git diff HEAD                           # See uncommitted changes (if any)
git log main..HEAD --oneline            # Commits to be included in PR
git diff main...HEAD                    # Full diff against base branch
git branch --show-current               # Current branch name
```

**Important:** Ensure all changes are committed before creating PR. If uncommitted changes exist, use the git-commit-validator skill first.

### Step 2: Determine Base Branch

Check for common base branch names:
```bash
git rev-parse --verify main 2>/dev/null && echo "main" || git rev-parse --verify master 2>/dev/null && echo "master"
```

Or check remote default:
```bash
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
```

### Step 3: Generate PR Title

**Format:** `type(scope): description` (conventional commits)

**Rules:**
- Max 50 characters
- Lowercase type from: feat, fix, docs, refactor, test, chore, perf, ci, build, style, revert
- Optional scope in parentheses
- Imperative mood ("add" not "added")
- No period at end

**Title should summarize the entire PR, not just the last commit.**

Analyze all commits in the PR:
```bash
git log main..HEAD --oneline
```

Synthesize into a single title that captures the overall change.

### Step 4: Generate PR Body

**Use this exact format:**

```markdown
## Summary
[1-3 sentences explaining what this PR does and why]

## Changes
- [Bullet list of key changes]
- [Focus on what matters, not every file touched]

## Test Plan
[How changes were validated - tests run, manual verification, etc.]

Closes #123
```

**Body Guidelines:**
- Summary: Brief context for reviewers, focus on WHY
- Changes: Key modifications, not exhaustive file list
- Test Plan: How you verified the changes work
- Issue reference: Include if applicable (Closes, Fixes, Resolves)

### Step 5: Create PR

**Default: Create as draft** (per project standards)

Use HEREDOC for proper body formatting:
```bash
gh pr create --draft --title "type(scope): description" --body "$(cat <<'EOF'
## Summary
Brief explanation of what and why.

## Changes
- Key change 1
- Key change 2

## Test Plan
How this was tested.

Closes #123
EOF
)"
```

**For ready-for-review PRs** (when user explicitly requests):
```bash
gh pr create --title "..." --body "..."
```

## Validation Rules

### Title Validation

1. **Max 50 characters** - Truncate or rephrase if over
2. **Format check** - Must match: `^[a-z]+(\([a-z0-9\-]+\))?!?: .+$`
3. **Valid type** - One of: feat, fix, docs, refactor, test, chore, perf, ci, build, style, revert
4. **Imperative mood** - "add feature" not "added feature"
5. **No period at end**

### Body Validation

1. **Has Summary section** - Required
2. **Has Changes section** - Required (at least one bullet)
3. **Has Test Plan section** - Required
4. **Concise** - 2-3 paragraphs max in summary
5. **No AI attribution** - No "Generated by", "Created with AI", etc.

### Pre-flight Checks

Before creating PR:
1. Branch has commits ahead of base
2. No uncommitted changes (or commit them first)
3. Branch is pushed to remote
4. No existing PR for this branch (unless intentional)

```bash
# Check if PR already exists
gh pr list --head "$(git branch --show-current)" --state open
```

## Type Reference

| Type | Use For |
|------|---------|
| `feat` | New feature or capability |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `refactor` | Code restructuring (no behavior change) |
| `perf` | Performance improvement |
| `test` | Test additions/fixes |
| `chore` | Maintenance, deps, config |
| `ci` | CI/CD changes |
| `build` | Build system changes |
| `style` | Formatting (no logic change) |
| `revert` | Reverting previous changes |

## Examples

### Simple Feature PR

**Title:**
```
feat(auth): add OAuth2 login support
```

**Body:**
```markdown
## Summary
Adds Google OAuth2 as an authentication option alongside existing email/password login.

## Changes
- Add OAuth2 provider configuration
- Create OAuth callback handler
- Add "Login with Google" button to login page

## Test Plan
- Tested OAuth flow locally with test credentials
- Verified token refresh works correctly
- Existing email login still works

Closes #45
```

### Bug Fix PR

**Title:**
```
fix(api): resolve timeout on large file uploads
```

**Body:**
```markdown
## Summary
Large file uploads were timing out due to default 30s limit. Increased timeout and added progress tracking.

## Changes
- Increase upload timeout to 5 minutes
- Add upload progress callback
- Better error messages for timeout scenarios

## Test Plan
- Uploaded 500MB file successfully
- Verified timeout error message when server unreachable

Fixes #128
```

### Refactoring PR

**Title:**
```
refactor: consolidate auth middleware
```

**Body:**
```markdown
## Summary
Auth checks were scattered across three middleware files. Consolidated into single auth module for consistency.

## Changes
- Merge auth middleware into single module
- Update route imports
- Remove deprecated auth helpers

## Test Plan
- All existing auth tests pass
- Manual verification of protected routes
```

## Why Draft by Default?

Draft PRs signal the work is ready for early feedback but may not be complete. Benefits:
- Allows CI to run before requesting reviews
- Enables async collaboration on in-progress work
- Prevents accidental merges of incomplete work
- Clear signal when ready: mark ready for review

To create a non-draft PR, user must explicitly request it.

## Error Handling

| Error | Resolution |
|-------|------------|
| No commits ahead of base | Ensure work is committed |
| Branch not pushed | Push with `git push -u origin HEAD` |
| PR already exists | Show existing PR URL, ask if update intended |
| Auth failure | Run `gh auth login` |
| Title too long | Shorten or rephrase |