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

• Max 50 characters - Truncate or rephrase if over

• Format check - Must match: ^[a-z]+(([a-z0-9-]+))?!?: .+$

• Valid type - One of: feat, fix, docs, refactor, test, chore, perf, ci, build, style, revert

• Imperative mood - "add feature" not "added feature"

• No period at end

Body Validation

• Has Summary section - Required

• Has Changes section - Required (at least one bullet)

• Has Test Plan section - Required

• Concise - 2-3 paragraphs max in summary

• No AI attribution - No "Generated by", "Created with AI", etc.

Pre-flight Checks

Before creating PR:

• Branch has commits ahead of base

• No uncommitted changes (or commit them first)

• Branch is pushed to remote

• 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