pr-create
Creates a pull request for the current branch.
SKILL.mdskills/pr-create/SKILL.md
GitHubRequired <project-root>/docs reads
Read these project-root spec files before creating the PR (use shell cat/ls — they may be in .gitignore, invisible to built-in search). Missing file → fall back to native tools, note the gap; never invent contents.
<project-root>/docs/git-hosts.md<project-root>/docs/issue-trackers.md
Operations
MCP tools take business-level inputs (title, body, base, head). Never use CLI flags. Skip --body-file temp-file steps when using MCP.
Operations: detect branch+default base, check uncommitted, fetch base+compute diff, push branch, create issue, create PR, view PR, check auth — all git host operations (see <project-root>/docs/git-hosts.md in the project root). CLI fallback per <project-root>/docs/git-hosts.md for each operation. Ticket commenting uses the issue tracker update-ticket operation (see <project-root>/docs/issue-trackers.md in the project root).
Follow <project-root>/docs/git-hosts.md in the project root for all git/gh operations.
The parent owns Steps 1-10. On NOTHING_TO_SHIP, proceed to Step 3 blockers.
1. Interpret Arguments
- Map inputs: base branch (e.g.,
main) →<base>; auto-create ticket →<ticket-mode>=auto; ticket URL/reference →<ticket-url>and<ticket-mode>=provided; skip ticket →<ticket-mode>=skip; guidance/focus areas →<additional-context>; no base → detect default branch in Step 1.
2. Load & Analyze Changes
Step 1: Determine context. Get the current branch via git branch --show-current (per <project-root>/docs/git-hosts.md in the project root). If <base> is not provided, detect the default via git remote show origin | grep "HEAD branch" | awk '{print $NF}' (per <project-root>/docs/git-hosts.md in the project root).
Store <current-branch> and <resolved-base> (user <base> or detected default; strip origin/ prefix). Use <remote-base> = origin/<resolved-base> for all comparisons; the local base is often stale.
Step 2: Load changes. Run git status --short and git fetch origin <resolved-base>. Then diff against <remote-base> using three-dot syntax (...) to exclude base-branch-only changes: ahead log, git diff --stat, git diff. Store as <changes>. Three-dot is mandatory.
3. Check Blockers
- Uncommitted changes: STOP (report + list files). On base branch: STOP (suggest
git checkout -b <feature-name>). No changes: STOP (report "Nothing to include in a PR.").
4. Summarize Changes
If <change-summary> was forwarded, reuse it verbatim and skip re-analysis. Otherwise derive it from commits ahead of <remote-base>: review commit messages, group into 2-4 logical themes, and summarize what and why (not how). Don't describe base-branch-only work. Store as <change-summary>.
5. Resolve Ticket
- If
<ticket-mode>is already set, don't ask. Otherwise, if thequestiontool is available, ask one question (headerProvide Ticket) with optionsAutomatically Create/Skipand custom answers enabled. If noquestiontool, set<ticket-mode>=skipand<ticket-url>=SKIPPED. - Normalize:
Automatically Create→auto; custom URL →provided;Skip→skip.
6. Load PR Template — BLOCKER
Mandatory gate. Do not compose <pr-body> (Step 7) until this completes. Most common failure mode.
Check the repo for a GitHub PR template. Store the raw text as <pr-template> (verbatim: headings, placeholders, reviewer checkboxes). Do not fill yet — Step 7 fills it. No template found → <pr-template> = none. Re-probe before accepting none.
7. Generate Metadata + Prepare Ticket Reference
Generate <pr-title>, <pr-body>, <ticket-title> (when <ticket-mode> = auto), and <ticket-body> (when auto) from <resolved-base>, <ticket-mode>, <ticket-url> (when provided), <additional-context>, and <pr-template> (from Step 6).
When <ticket-mode> = auto: reuse <change-summary> themes based on actual commits/diff. Title (max 70 chars) reflecting the delivered outcome. Description: what and why. Checklists: 2-4 functional sections plus a final Validation section (reviewer-facing: "Verify that...", "Confirm that..."). Create via git host create issue (see <project-root>/docs/git-hosts.md in the project root, title, body, assignee @me) or CLI fallback per <project-root>/docs/git-hosts.md with a temp file. No attribution lines. Store the issue URL as <ticket-url>.
Otherwise: provided → use provided value; skip → SKIPPED.
Compose <pr-body> based on <pr-template>:
- When
<pr-template>≠none: use it verbatim as the body skeleton. Fill placeholders/sections (e.g.,## Ticket,## Description,## Checklist) with content derived from<changes>and<ticket-url>. Preserve template structure, headings, and required reviewer checkboxes verbatim — only fill content, don't restructure. Do NOT use the hardcoded body in §9. - When
<pr-template>=none: fall back to the default body structure in §9.
8. Push Branch
Push with upstream via git host push (see <project-root>/docs/git-hosts.md in the project root) or git push -u origin <current-branch> per <project-root>/docs/git-hosts.md. Report Push: yes/no (report no if "Everything up-to-date"). Store <push-status> and <pushed-line>.
9. Create PR
Use <pr-title> and <pr-body> from Step 7. <pr-body> already reflects <pr-template> (filled template when present, default structure otherwise). Title (max 70 chars) → <pr-title>. Description: brief intent/scope. Checklist: 2-4 functional sections plus Validation.
- Body (when
<pr-template>=none):
## Ticket
<ticket-url>
## Description
<short-description>
## Checklist
<checklist-items>
When <pr-template> ≠ none, use the filled template from Step 7 as the body. No attribution lines. Preserve markdown newlines (single-line strings render \n literally). Prefer git host create PR (see <project-root>/docs/git-hosts.md in the project root, title, body, base, head, assignee @me). CLI fallback per <project-root>/docs/git-hosts.md: write the body to a temp file, then run gh pr create --title "<pr-title>" --body-file /tmp/pr-body.md --base "<resolved-base>" --head "<current-branch>" --assignee "@me". If the PR exists, use git host view PR (see <project-root>/docs/git-hosts.md in the project root, pr_ref=<current-branch>, fields=url,number) or gh pr view <current-branch> --json url,number per <project-root>/docs/git-hosts.md. Store the URL as <pr-url>. Verify the rendered body via git host view PR (fields=body) or gh pr view <current-branch> --json body | jq -r '.body' per <project-root>/docs/git-hosts.md; re-edit if needed. Output the PR URL when created or if it already exists.
10. Link PR in Ticket(s)
Gate: skip when <ticket-url> = SKIPPED AND <pr-body> references no issues.
Collect every unique issue reference: <ticket-url> (when not SKIPPED) plus any other issue URLs or #N/OWNER/REPO#N references in <pr-body> (#N resolves against the current repo). For each, post the comment PR: <pr-url> via the issue tracker update-ticket operation (see <project-root>/docs/issue-trackers.md in the project root). CLI fallback per <project-root>/docs/issue-trackers.md: gh issue comment <issue-ref> --body "PR: <pr-url>". Report any ticket lacking a matching tracker operation instead of skipping silently.