/pr-creation

name: pr-creation
description: "MUST be used when creating pull requests. Handles context gathering, title generation (conventional commit format), body formatting, and PR creation via GitHub CLI. Creates PRs as drafts by default. Triggers on: 'create PR', 'open PR', 'ready for review', 'push for PR', 'send for review'."
allowed-tools:
  - Bash(git:*)
  - Bash(gh:*)
  - Read
  - Grep

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

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:

git rev-parse --verify main 2>/dev/null && echo "main" || git rev-parse --verify master 2>/dev/null && echo "master"

Or check remote default:

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:

git log main..HEAD --oneline

Synthesize into a single title that captures the overall change.

Step 4: Generate PR Body

**Use this exact format:**

## 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:

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):

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)

# 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:**

## 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:**

## 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