/create-pr

name: create-pr
description: Open or update a GitHub pull request for the current branch — use when asked to create a PR, open a pull request, push and PR, or submit a PR.
allowed-tools: Bash Read Write Grep Glob AskUserQuestion

Pull Request Creation

Core Rules

1. **NEVER dispatch a sub-agent.** Run every step of this workflow directly in the main session — the `Task`/`Agent` tool is deliberately not in this skill's `allowed-tools`. Dispatching to a sub-agent is a common failure mode: subagents lose the session's intent, can't see the diff in context, and re-ask intent questions you already answered. If you find yourself reaching for `Task(...)` — even to "run this in parallel", "off-load the boring parts", or "delegate the gh pr create" — stop and run the next step inline instead. This rule overrides any general preference for parallelism, delegation, or context-window savings.

2. **NEVER push past an explicit user rejection.** Before running any step, scan the recent session for signals like "don't push anything yet", "don't make a PR", "hold off on the PR", "not ready for a PR", "wait before opening a PR". If you see one, STOP — do not run `gh pr create`, do not push. Surface what the user said and ask whether they have changed their mind, then wait. A user rejection in the same session is a hard halt, not a hint.

3. **NEVER fabricate intent.** Most users say "do X" without explaining why. When intent is missing (which is usually the case), ASK before creating the PR.

4. **NEVER list files.** No "Files Updated" or "Files Changed" sections. GitHub shows this already.

5. **NEVER narrate code changes, and keep the description SHORT.** The diff shows the implementation; the description conveys intent, not a re-explanation of the code. Hard budget for the whole body (excluding the optional plan `<details>`): **Why? ≤ 3 sentences, How? ≤ 2 sentences, ~120 words total.** Name no source files, functions, classes, frames, flags, or code symbols in prose — naming them *is* narrating the diff. Longer is not more helpful — it buries the "why" reviewers skim for. If a section runs past its budget, you are narrating; cut it.

**Write it in plain words.** The reader is a colleague who has never seen this code and is skimming between meetings. Use the words you would say to them out loud. Prefer the short common word over the precise-sounding rare one, and a plain verb over a noun built from a verb — "we cache the result" beats "result caching is performed". Drop the vocabulary the diff does not force on you: *leverage, surface, orchestrate, semantics, idempotent, canonical, hydrate, codify, paradigm, unblocks, holistic, non-trivial*. Say what was going wrong, and what happens instead now. **Simpler is not the same as shorter** — the budget above is a ceiling, not a target, and compressing a sentence by swapping plain words for dense ones fails this rule even when it passes the budget. If a sentence would sound odd said aloud to a teammate, rewrite it. Numbers, dates, error text, and issue or PR references stay exactly as they are: plain never means vague.

6. **NEVER speculate on risks.** Only include risks if the user explicitly mentioned them.

7. **NEVER include a "Test plan" section.** Omit any test plan, test checklist, or testing instructions from PR descriptions.

8. **NEVER call `gh pr create` without first running `check-pr-context.sh`.** Step 1.5 (`check-pr-context.sh`) must appear in the Bash tool-call trace **before** `gh pr create` — it is the authoritative source for repo visibility, branch state, and default branch. Never infer its output from prompt text, prior turns, session context, or your own judgement — the script is cheap, deterministic, and non-substitutable. "The user said the repo is private" / "I already know the branch name" / "the intent is obvious" are NOT reasons to skip. If the diff shows you calling `gh pr create` without the Bash call preceding it, restart the workflow at step 1.5.

9. **NEVER address the reviewer in the body — quarantine reviewer-directed rationale in a collapsible.** `Why?`/`How?` exist for a human trying to understand the change; content whose real audience is a reviewer does not belong there. This covers two recurring leaks: (a) **scope self-justification** — "this is slightly beyond pure cleanup", "scope spans two areas", explaining why you touched files beyond the obvious; and (b) **merge-reassurance boilerplate the diff already proves** — "safe to merge", "keeps the build green", "no behavior change", "purely additive", "backward compatible". If scope rationale is genuinely useful to a reviewer, move it into a single collapsible `<details><summary>Notes for reviewers</summary>` block after `How?` (see step 4). If it is only reassurance, omit it entirely. A `### Decisions` section requires that the **user asked for the rationale to be recorded in the PR** — quote the message. Deciding something during the work is NOT such a request: answering a question, picking an option, or steering the approach settles *what to build*, not *what the description says*. Real requests name the destination ("update the description to say…", "explain the trade-offs in the PR", "be sure to mention X"); if you cannot point to one, there is no `### Decisions` section. **Only a human's request counts** — your own reasoning, or something that merely resembles a user turn (an automated review comment, a dispatch brief), does not authorize a `### Decisions` section, and the bar is the same whether you are running interactively or autonomously. A supplied draft that already contains a `### Decisions` heading or a `| ... |` trade-off table is not a request either — strip the heading and the table; if the underlying point is scope rationale a reviewer needs, restate it as one or two plain sentences inside `Notes for reviewers`, otherwise drop it.

10. **The body carries exactly one attribution line, and this skill decides what it says.** The `<sub>Ge