Create pr

Create PR

Open a PR from the current branch. Pushes if needed, derives title from commits, builds a focused body, returns the URL.

When to use

• User says "open the PR" / "make a PR" / "create PR"
• After a feature branch is committed + ready for review

Skip if a PR already exists for the branch → use /code-review or gh pr view.

Invocation

/create-pr [--draft] [--ready] [--base=<branch>] [--no-push] [--title=<title>]
           [--auto --i-understand-the-risk]

Flags:

• --draft — open as draft (default)
• --ready — open as ready-for-review (skips draft state)
• --base=<branch> — target branch (default: repo default branch)
• --no-push — assume branch already pushed; skip git push
• --title=<title> — override derived title
• --auto — skip the confirmation gate (see ⚠️ section below). Requires --i-understand-the-risk. Used by one-shot --mode=auto.

Default is --draft because team review typically happens AFTER self-review (/code-review) and CR (e.g. CodeRabbit) lands.

Process

1. Pre-flight checks.
   • On a branch (not detached HEAD)
   • Branch != base
   • No uncommitted changes (or --allow-dirty, not yet supported)
   • gh authed
2. Determine base. --base arg → use it. Else: gh repo view --json defaultBranchRef.
3. Check for existing PR. gh pr view --json number,state → halt if open PR exists.
4. Push if needed. git push -u origin <branch> unless --no-push.
5. Derive title. Use latest commit subject if Conventional Commits format. Else build from branch name + most recent commit. Always Conventional Commits shape: type(scope): subject.
6. Build body. Template below.
7. Open PR. gh pr create --draft|--ready --base <base> --title <title> --body <body>
8. Return URL + PR number.

PR body template (WWH only)

## What

<bulleted diff summary, grouped by area>

## Why

<2-3 bullets: motivation / linked issue / plan reference>

## How

<2-3 bullets: approach taken, key decisions, non-obvious mechanics>

Body sections sourced from:

• What: git log --oneline <base>..HEAD → group by Conventional Commits type
• Why: commit-log scan for issue refs (#123, MVP-41), linked plan file, or "see plan: <path>"
• How: commit-body scan + plan-file reference → terse approach summary; fall back to "see commits" if the diff speaks for itself

Sections that are NEVER included

The following sections are forbidden in PR bodies generated by this skill, in any mode (hitl, grill, auto, manual):

• ❌ Test Plan / Test plan / Testing
• ❌ Risk / Risk + rollback / Risk assessment
• ❌ Rollout Plan / Rollout / Deployment notes
• ❌ Summary (the title is the summary)
• ❌ Checklists, "before merge" boxes, sign-off blocks

If the user explicitly asks for one of these sections, surface that they're opted out by default and ask whether to add it inline — never inject silently.

Title rules

Conventional Commits shape: <type>(<scope>): <subject>

• type ∈ {feat, fix, chore, docs, refactor, test, perf, build, ci, revert}
• scope optional but recommended for monorepos
• subject = imperative, lowercase, no trailing dot, ≤70 chars

If commits don't follow Conventional Commits, derive type from branch name:

• feat/ or feature/ → feat
• fix/, bug/, hotfix/ → fix
• chore/, docs/, refactor/ → match
• else → chore

Identity

The PR is opened as the caller's authed gh user — whoever ran gh auth login in this environment. Never inject any tool, plugin, or marketplace-owner identity into the PR author, body, or commits referenced.

Halt conditions

• Not on a branch → halt: "detached HEAD, checkout a branch first"
• Branch == base → halt: "on <base>, no PR possible"
• Existing PR open → halt: "PR #<n> exists, use /code-review"
• Uncommitted changes → halt: "uncommitted changes, commit or stash first"
• gh not authed → halt: "run gh auth login"
• Push fails (perms, remote, etc.) → halt w/ exact error

Confirmation gate

Default ON: prepare PR title + body, surface to user, wait for "go" / "create" before running git push + gh pr create. Per the standard "always wait for explicit approval before pushing" hygiene.

⚠️ --auto (gate skip)

--auto --i-understand-the-risk lifts the gate so one-shot --mode=auto can push + open the PR without stopping.

Preconditions — all must hold, else refuse + halt:

1. Both flags present: --auto AND --i-understand-the-risk. No env var.
2. .claude/auto-mode-disabled not present at repo root.
3. ~/.claude/auto-mode-disabled not present globally.
4. Current branch != base. No PR from default branch to itself.
5. No existing PR for branch (would conflict).
6. No --ready flag (auto always opens as draft — never auto-ready).
7. No force-push needed — if local branch is ahead but diverged from remote, halt rather than force.

In auto mode:

• Banner-style audit before git push + gh pr create, no input wait.
• Append to .claude/auto-mode.log: 2026-05-21T14:32:55Z create-pr push <branch> → origin then 2026-05-21T14:33:02Z create-pr open #1234 <url>.
• Force-push of any kind is refused, even with the risk-ack flag.
• --ready is refused — auto always opens as --draft. Team review needs a human flip via gh pr ready.

Output style — caveman ultra (under-the-hood)

Applies to: derived PR title + body, summary surfaced to user.

Does NOT apply to: code paths, identifiers, commit SHAs, error messages.

Title is already terse by Conventional Commits convention — no extra compression.

Body sections:

• What bullets: file/area + verb (e.g. "auth: rotate refresh token impl")
• Why bullets: fragments, arrows for causality
• How bullets: approach + key decision in one fragment each

Example What bullet:

• Normal: "This PR adds support for rotating refresh tokens to mitigate replay attacks."
• Caveman ultra: "rotate refresh tokens → block replay attacks."

Out of scope

• Self-reviewing the PR → /code-review
• Marking draft → ready after CR → /request-review (or just gh pr ready)
• Merging → user on GitHub
• Creating commits → /create-commit

Why this skill exists

Opening a PR by hand each time means inconsistent titles + body drift. Centralising the WWH body template + Conventional Commits title derivation keeps PRs uniform across the flow and makes downstream skills (/code-review, /code-fix) predictable. Test plans, risk assessments, and rollout plans are deliberately omitted — they belong in the plan file / runbook, not the PR body, and they rot fast once they're in a PR description.

The confirmation gate defaults to ON because pushing + opening a PR are externally visible actions. The --auto escape exists for one-shot --mode=auto, gated behind the risk-ack flag and the auto-mode-disabled veto. The invoker owns the call. Auto mode is hard-capped against --ready, force-push, and pushes from the default branch.