create-pull-request

name	create-pull-request
description	Canonical rules for creating GitHub pull requests via `gh` - title, body format, visibility gate, and creation workflow. Load on any intent to open, create, or draft a pull request. Triggers include explicit asks ("open PR", "create PR", "gh pr create", "ship PR", "draft PR", "let's PR this") and implicit signals (user just finished a branch and is wrapping up, related slash command invoked).

GitHub pull requests

Canonical source for PR title, body, and creation workflow. Mirrors the commit visibility gate from git-commit-message.

Hard rules

• Never open a PR without explicit user request. "Done" is not a PR. Wait for "open PR", "ship it", or equivalent.
• Permission to PR is per-action, not autonomous mode. Does not waive any validation, gate, or skill workflow.
• Never include: co-authors, AI attribution, "Generated by Claude" footers.
• FORBIDDEN: history rewrites before PR - no git rebase, commit --amend, push --force. Push the branch as-is.

Format

Title + markdown body. No prose paragraphs in body.

type(scope): subject

- bullet 1
- bullet 2
- bullet 3

Rules:

• Title: same rules as commit subject. Imperative, lowercase after colon, ≤70 chars total. Conventional commit format (type(scope): subject).
• Body: bullet list only. No headers (## Summary, ## Test plan, ## Notes). Add headers only if user asks.
• Bullets: 3-7 words. Capture "why" and user-visible behavior.
• Standard markdown only. No em-dashes, curly quotes.
• Issue refs: use fix #123, close #456, related #789 inside bullets (same rules as git-commit-message).

Type / scope

Same inference rules as git-commit-message. Priority for scope:

1. User-provided
2. Jira/ticket ID matching [A-Z]{3}-[0-9]+ from branch name
3. Branch name
4. Affected module

Workflow

1. Confirm base branch. Default is repo default (usually main/master). User specified other base: use it.

2. Read branch diff vs base. git diff <base>...HEAD and `git log

   ..HEAD`. Understand full branch, not just last commit.

3. Compose title + body per format above.

4. Push branch if needed. Check git status for unpushed commits. Push to origin with upstream if first push.

5. Show, then create (visibility gate):

   • Output the full title and body as a markdown code block in chat.
   • Immediately call gh pr create with the same content in the same turn. Do NOT end the turn between message and PR creation.
   • Never create the PR without showing the content first.
   • Never show the content and end the turn without creating (unless user invoked compose-only path; see below).

6. Pass the body via heredoc on stdin to preserve formatting:

   gh pr create --draft --title "type(scope): subject" --body-file - <<'EOF'
   - bullet 1
   - bullet 2
   EOF
   

   Drop --draft only if user asks for a ready PR.

7. Return the PR URL from the command output.

Compose-only path

When the user wants the content but not the PR ("just compose it", "don't open yet"):

• Output title + body as a code block in chat.
• Do NOT call gh pr create.

The visibility gate (step 5) does not apply on this path.

Why these rules

• Show + create in same turn: same rationale as commit gate. See git-commit-message for full reasoning. User reviews title, body, and diff together, approves whole turn at once. No double round-trip.
• --body-file - with heredoc: shell-escaping multiline markdown with --body "..." breaks on quotes, drops newlines, mangles backticks. Stdin sidesteps shell quoting entirely.