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 unreachable

Fixes #128

Refactoring PR

Title:

refactor: consolidate auth middleware

Body:

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