create-github-pr

name	create-github-pr
description	Use whenever asked to create GitHub Pull Request.
allowed-tools	Bash(*scripts/get-pr-info.sh) Bash(gh pr create*) Bash(git checkout*) Bash(git push*) Bash(git switch*)
compatibility	Requires gh CLI and git

Create GitHub Pull Request

Overview

Create GitHub Pull Requests with comprehensive analysis and interactive confirmation. Analyzes all commits in the branch, generates the PR title, uses the pr-description skill for the PR body, and creates the PR using gh CLI.

Workflow

1. Analyze branch state
2. Review all changes and commits
3. Generate PR title and body
4. Interactive confirmation (confirm/regenerate/edit/cancel)
5. Push and create PR

Step 1: Analyze Branch State

Gather all PR information using the helper script.

scripts/get-pr-info.sh

Read the JSON output directly from the tool result.

Decision logic:

• If on_main == true: Analyze changes, recommend branch name, create branch (see below)
• If existing_pr_number != null: PR already exists, show error and exit
• If uncommitted == true: Warn user and suggest committing first
• If upstream_status == "behind": Suggest pulling first
• If has_upstream == false: Will need to push with -u flag

Creating a new branch from main/master:

1. Analyze uncommitted changes to understand what they contain
2. Generate a recommended branch name: short-summary-with-dashes
   • Examples: add-user-authentication, fix-login-bug, update-docker-config
3. Present recommendation using AskUserQuestion:
   • Question: "Create new branch from {current_branch}?"
   • Header: "Branch name"
   • Options: ["recommended-name" (Recommended)]
   • User can select recommended name or choose "Other" to provide custom name
4. Create and checkout the branch:

git checkout -b "$branch_name"

Step 2: Review All Changes

Understand the FULL scope of changes that will be in the PR. The output from Step 1 already contains commits and stats.

git diff origin/<base_branch>...HEAD

Display to user: current branch, base branch, commit count, list of commits, files changed, and insertions/deletions — all from the Step 1 output.

Critical: Analyze ALL commits in the branch to understand the full context. The script provides commit hashes and messages - use git show for detailed inspection if needed.

Step 3: Generate PR Title and Body

Based on ALL the commits and changes, generate a concise title here and use the pr-description skill to draft the body.

Project title policy

Before applying the default title format, check whether the repository enforces PR title rules. Look for title validation in project docs and automation, especially .github/workflows/, .github/actions/, Dangerfile, commitlint configuration, merge queue/merge rules, or actions such as semantic-pull-request, validate-pr-title, and pull-request-title.

If a project-specific PR title policy exists, follow that policy exactly and mention it in the preview. The local policy overrides the default format below. If a title check exists but the expected format is not clear, stop and ask for clarification instead of guessing.

Title format

Use this default only when no project-specific PR title policy exists. Follow this format: <type>: <description>

• Keep under 70 characters
• Prefix with change type (like feat)
• Use imperative mood (same as commit messages)
• Be specific but concise
• Example: "feat: add user authentication with OAuth2 support"

Title prefix types

Type	Purpose
feat	New feature
fix	Bug fix
docs	Documentation only
style	Formatting/style (no logic)
refactor	Code refactor (no feature/fix)
perf	Performance improvement
test	Add/update tests
build	Build system/dependencies
ci	CI/config changes
chore	Maintenance/misc
revert	Revert commit

Body format

Load the pr-description skill for the PR body.

Pass it the complete context from Step 1 and Step 2, including the branch diff, commits, any linked issue, and the pr_template value if one exists.

The pr-description skill owns:

• following the repository template when present
• keeping the description concise and human-readable
• focusing on why and reviewer-relevant outcome
• asking the user clarifying questions before updating the PR if the rationale is unclear
• stopping before PR creation or PR body updates when user-provided motivation is missing

Do not bypass that skill by inventing a body here. If pr-description requires user motivation, ask the user and stop until they provide it.

Step 4: Interactive Confirmation

Present the generated PR metadata clearly to the user:

Generated PR:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title: [PR title]

Body:
[Generated by `pr-description`]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Branch: [current-branch] → [base-branch]
Commits: [N commits]

Then ask using AskUserQuestion:

• Question: "How would you like to proceed with this pull request?"
• Header: "Create PR"
• Options:
  • "Confirm and create PR" (recommended)
  • "Regenerate title/body"
  • "Edit title/body manually"
  • "Cancel"

Handle responses:

• Confirm: Proceed to Step 5 immediately
• Regenerate: Go back to Step 3, generate different title/body (vary approach)
• Edit: Ask user for custom title and body, then proceed to Step 5
• Cancel: Exit gracefully, inform user no PR was created

Step 5: Push and Create PR

Push the branch if needed, then create the PR using gh CLI. Use the upstream info from Step 1.

Push if needed (use has_upstream / upstream_status from Step 1 to decide), then create the PR:

git push -u origin <branch>   # new branch
# or
git push                       # existing upstream

gh pr create --title "<title>" --body "<body>"

Show the PR URL with gh pr view --json url --jq .url.

Alternative: Create Draft PR

If changes are work-in-progress, offer to create as draft:

gh pr create --draft --title "..." --body "..."

Best Practices

• Analyze ALL commits: Don't just look at latest commit, review entire branch
• Concise title: Under 70 characters, imperative mood
• Delegate the body: Use pr-description instead of hand-rolling PR copy here

Safety Protocol

• NEVER create PR from main/master branch
• NEVER force push unless explicitly requested
• NEVER create PR with uncommitted changes without warning user
• ALWAYS show user what will be in the PR before creating
• ALWAYS wait for confirmation before creating PR
• Check for existing PRs for the current branch before creating
• If the rationale for the PR body is unclear, stop and ask before updating it
• If the user has not explicitly provided motivation for the PR body, stop and ask before creating or updating the PR

Error Handling

Branch Already Has PR

The script already checks for existing PRs. If existing_pr_number is non-null in the Step 1 output, inform the user and stop.

Uncommitted Changes

If uncommitted == true from Step 1, warn user:

⚠️  Warning: You have uncommitted changes.
It's recommended to commit these before creating a PR.

Would you like to:
1. Commit changes first (recommended)
2. Create PR anyway (changes won't be included)
3. Cancel

Not On a Branch

If detached HEAD or other issue:

Error: Not on a branch. Create a branch first:
  git checkout -b feature/my-feature

Usage Examples

Simple invocation

User: "create a PR" or "create pull request"

→ Checks branch state
→ Analyzes all commits
→ Generates title/body
→ Shows preview
→ Asks: Confirm/Regenerate/Edit/Cancel
→ Creates PR on confirmation

With base branch specified

User: "create PR to develop branch"

→ Uses 'develop' as base instead of main
→ Continues with workflow

Draft PR

User: "create draft PR"

→ Follows normal workflow
→ Creates as draft PR (--draft flag)