Create PR Skill

Generate and create/update a comprehensive PR using the shared body template.

Mode detection

Parse $ARGUMENTS:

• Starts with --update or -u followed by a number → Update Mode on that PR.
• Anything else → Create Mode (argument is the base branch; default main).

Create Mode

0. Rebase first

Run the sync-branch skill before reading the diff. A PR opened from a branch behind origin/${BASE:-main} shows reviewers a diff against the wrong merge base, and its CI result describes code that will not merge.

Opening a PR is explicit direction to publish the branch, so this is the one caller for which sync-branch may force-push. It pushes once, here — not again in step 4.

1. Gather diff information (parallel)

git log origin/${BASE:-main}..HEAD --oneline
git diff origin/${BASE:-main}...HEAD --stat
git diff origin/${BASE:-main}...HEAD

2. Detect the design context

Changed paths → change type:

Path pattern	Change type
infrastructure/base/crossplane/configuration-aws/configuration-packages.yaml (composition package pin)	composition
opentofu/**/*.tf, terramate.tm.hcl	infrastructure
*networkpolicy*, *rbac*, openbao/**, *cilium*policy*	security
Multiple top-level dirs + HelmRelease/Kustomization	platform

Find the design document behind these changes, if one exists. Non-trivial work goes through the Superpowers flow (see docs/superpowers/AGENTS.md), which commits a design and a plan on the branch:

git diff origin/${BASE:-main}...HEAD --name-only \
  | grep -oE 'docs/superpowers/(specs|plans)/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9-]+\.md' \
  | sort -u

When a design is detected, include the Design block:

## 📋 Design

Design: [`<date>-<topic>-design.md`](../blob/main/docs/superpowers/specs/<date>-<topic>-design.md)
Plan: [`<date>-<topic>-plan.md`](../blob/main/docs/superpowers/plans/<date>-<topic>-plan.md)

<one line: which part of the plan this PR delivers>

If the design doc itself changed materially in a PR that also implements it, say so in the summary — a design moving during implementation usually signals scope creep worth calling out.

If the changes look substantial (a new composition, a new OpenTofu stack, a security-model change) and no design doc is present, include the Design Recommendation warning block from the template.

3. Render the PR body

Fill the template in templates/pr-body.md. Apply the mermaid styling from references/mermaid-styles.md. Keep title < 70 chars. Drop sections that do not apply (no empty stubs).

4. Create the PR

git push -u origin "$(git branch --show-current)"
gh pr create --base "${BASE:-main}" --title "<title>" --body "$BODY"

5. Output

Return only the PR URL.

Update Mode

gh pr view "$PR_NUMBER" --json number,title,files,additions,deletions,baseRefName,body
gh pr diff "$PR_NUMBER"

Generate a fresh body using the same template. Update through the REST endpoint — gh pr edit runs a GraphQL query that includes projectCards, which GitHub has sunset, and on this repo it fails outright while printing what looks like a deprecation warning. Verified 2026-09-17: the body was unchanged afterwards.

gh api --method PATCH "repos/{owner}/{repo}/pulls/$PR_NUMBER" -f body="$BODY" --jq '.number'

Return Updated PR #<N>: <url>.

Content rules

• Title: conventional prefix (feat(crossplane): ...), under 70 chars.
• Summary: WHY, not WHAT. The file table shows WHAT.
• Auto-detect the design by scanning docs/superpowers/specs/*-design.md in the diff. Preserve existing references on update.
• Never skip hooks, never force-push without explicit user direction.

Related skills

• ship-it — the full pipeline; calls this skill as its last stage
• sync-branch — the rebase preflight in step 0
• superpowers:brainstorming — produces the design this PR references
• /commit — commit with pre-commit validation before creating the PR

Supporting files

• templates/pr-body.md — full body template with both design-present and design-recommendation variants
• references/mermaid-styles.md — color classes and best practices for flow diagrams