/create-pull-request

name: create-pull-request
description: 'Use when asked to create or update a PR, revise its description, or link issue references to its body. Not for multi-PR stacks: use gate-and-merge. Not for releases: use git-workflow-and-versioning.'
disable-model-invocation: true

Create pull request

Contract

| Field | Bound contract | |---|---| | Trigger | User asks to create a PR, open or update a draft PR, write or refresh a PR description, revise an existing PR body for reviewer context, or append GitHub issue and Linear ticket references to a PR body. | | Authority | Human-gated: requires explicit human invocation and preview confirmation before each remote mutation. The write set is one GitHub PR: create or update its title, body, draft state, head, and base, or append one `#### Issues` block to its body. Rollback is `gh pr edit` restoring the prior body or closing the created PR. | | Side effect | Creates or updates a GitHub PR with a descriptive title and body, optionally as a draft; rewrites an existing PR body; or appends one `#### Issues` block. Remote mutation on GitHub, bounded to one PR. | | Done | The mode's done state holds: a created or updated PR whose remote title, body, draft state, head, and base match the preview (full, quick); a remote PR body that gives reviewers context the diff cannot, confirmed by a fresh read (describe); or a fresh remote read showing one non-duplicate `#### Issues` block with both supplied references (link-issues). |

Inputs

Required:

• Mode: one of `full` (default), `quick`, `describe`, `link-issues`. Pick the mode from the user's ask, not by guessing.
• `gh` CLI installed and authenticated (`gh --version`, `gh auth status`).
• For `full` and `quick`: a current git branch that is not `main`/`master`, with commits ahead of the base branch, and the base branch confirmed against the repository default (quick mode rechecks this and rebases when the branch is stale).
• For `describe`: a PR number or URL and its diff context, retrieved via `gh pr diff` and `gh pr view --json files`.
• For `link-issues`: a PR identifier accepted by `gh pr view`, a GitHub issue reference, and a Linear ticket key, all supplied exactly. Do not infer, search for, or substitute a missing identifier. Accept an explicit repository when the PR is not resolvable from the current repository.

Optional:

• A related issue number, inferred from commit messages or branch name (`#123`, `fixes #123`, `closes #123`).
• A PR template at `.github/pull_request_template.md` (full mode only).
• Draft intent from the user.
• For an update in `full` or `quick`: the target draft PR identified by number, URL, or the current head branch. The target must be a draft; do not convert a ready PR to draft.
• For `describe`: the existing PR body via `gh pr view --json body` when revising.

Procedure

Mode full

Full mode fires when the user asks to create a PR, write a PR description, summarize changes for review, or open a pull request with the project's review/CI/testing rigor. It fills the project template, gates on review/CI/testing prerequisites, checks for an existing PR, and verifies in the browser.

1. Verify prerequisites: `gh` is installed and authenticated, and the working directory is clean (`git status`). If uncommitted changes exist, ask the user whether to commit, stash, or discard them before proceeding. Done when: `gh` is authenticated and the working directory is clean or uncommitted changes are surfaced for user decision. 2. Before creating a PR, ensure related review, CI, and testing workflows have been satisfied. Do not proceed with PR creation until those prerequisites are met. Done when: review, CI, and testing prerequisites are confirmed satisfied. 3. Check for an existing PR on the current branch: `gh pr list --head $(git branch --show-current) --json number,title,url`. If a PR already exists, show it and ask whether to view, update, or close-and-recreate; only create a new PR if none exists. For an update, verify the target is a draft; do not convert a ready PR to draft or select a PR by guesswork. Done when: existing PR status is confirmed and the action (create, view, update, or close-and-recreate) is determined. 4. Identify the current branch and the base branch (`git remote show origin | grep "HEAD branch"`). Refuse if on `main`/`master`; ask the user to switch to a feature branch. Done when: the current branch is not `main`/`master` and the base branch is identified. 5. Analyze the commits and diff for this PR: `git log origin/<base>..HEAD --oneline --no-decorate` and `git diff origin/<base>..HEAD --stat`. Extract the related issue number, change description, type of change, and test procedure from commit messages, branch name, and changed files. Done when: issue number, change description, type, and test procedure are extracted from commits and diff. 6. Generate a conventional title in the form `<type>(<scope>): <summary>` when the project uses conventional commits (detected from `feat:`/`fix:`/etc. commit prefixes or `feat/`/`fix:` branch prefixes); omit the scope when none is evidenced. Otherwise generate a descriptive, non-generic title. Append the issue number if found (`feat: ... (#123)` or `... (fixes #456)`). Done when: a descriptive, non-generic PR title is generated with a conventional-commits prefix and issue number when applicable. 7. Build the PR body from the project template at `.github/pull_request_template.md` if it exists; fill every applicable section with the gathered context (summary, related issue, testing, breaking changes, type-of-change checkboxes, checklist items). If no template exists, write a body with `## Summary` and `## Testing` sections: state what changed and why for reviewers, and record only observed test results (say `Not run` when no test result is available; give no invented reason). Add issue links, screenshots, rollout notes, or reviewer guidance only when supplied or verified. Done when: the PR body is built fr