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.