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:

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

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