Prisma Pull Request Creator

Create PR Skill

Instructions

Step 1: Gather Context

Detect the PR's base branch instead of hardcoding main. Set BASE_BRANCH once and reuse it in every diff/log command:

BASE_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's@^origin/@@')
BASE_BRANCH=${BASE_BRANCH:-main}

git rev-parse --abbrev-ref origin/HEAD returns the remote's default branch (e.g. origin/main); the sed strips the origin/ prefix. The fallback to main covers repos where origin/HEAD is unset. If you know the PR was branched off a non-default branch, override BASE_BRANCH explicitly before running the commands below.

1. Run git log "$BASE_BRANCH..HEAD" --oneline to see all commits on the current branch (fallback: git log "origin/$BASE_BRANCH..HEAD" --oneline).
2. Run git diff "$BASE_BRANCH...HEAD" --stat to see which files changed (fallback: git diff "origin/$BASE_BRANCH...HEAD" --stat).
3. Run git diff "$BASE_BRANCH...HEAD" to read the full diff (fallback: git diff "origin/$BASE_BRANCH...HEAD").
4. Check for local-only changes that won't be in the PR unless committed:
   • git status -sb
   • If there are uncommitted changes, explicitly call out that gh pr create can proceed but those changes will not be in the PR.

Step 2: Resolve the Linear Ticket

Resolve the Linear ticket from context — do not ask the user. The ticket is almost always derivable from one of:

1. The branch name. Most branches are named tml-NNNN-… (lower-case form of the Linear identifier). The current ticket is whatever matches (?i)\b(TML-\d+)\b in git rev-parse --abbrev-ref HEAD. Use the trailing slug from the branch name verbatim as $SLUG.
2. The conversation context. If the user previously linked or named a ticket in this conversation, use that.
3. The most recent commit messages on the branch. Look for a Refs: TML-NNNN or (TML-NNNN) trailer / mention in git log "$BASE_BRANCH..HEAD".

Extract:

• $TICKET_ID — the canonical upper-case identifier (e.g., TML-1859)
• $SLUG — the trailing slug used in Linear URLs (e.g., pn-add-more-parameterized-types); take it directly from the branch name's trailing portion when available

Only ask the user if all three sources fail to yield an identifier. In that case, ask once with a concrete proposal (e.g. "I couldn't infer a Linear ticket from the branch xyz or the recent commits — which ticket does this PR close?").

Step 3: Compose the PR Title

Format:

$TICKET_ID: <concise title in sentence case>

Rules:

• Always start with the Linear ticket ID followed by : then a single space.
• Sentence case after the colon (capital first letter; rest lowercase except proper nouns, package names, types, etc.).
• No period at the end.
• Aim for under 70 characters total. Optimise for information density, not raw character count — a slightly longer title that names the concrete deliverable is better than a short abstract one.
• The title must convey what concrete thing changed, not just an abstract scope. A teammate scanning a list of PR titles should be able to tell what this PR delivers without opening it.
  • Bad: TML-2375: expand pgvector type and operator surface (abstract)
  • Good: TML-2375: 5 new pgvector operator descriptors + HNSW index support (concrete)
• If the change spans multiple packages or layers, name the headline package or capability, not all of them. Secondary scopes belong in the body.

Examples:

• TML-1859: add text codec support to sql-runtime
• TML-2104: handle null in jsonb columns (postgres adapter)
• TML-2375: 5 new pgvector operator descriptors + HNSW index support
• TML-2456: split contract emission into two phases

Step 4: Compose the PR Description

The PR description must follow a decision-led, narrative structure. A teammate without prior context on the work should be able to read it top-to-bottom and understand what we decided, why, and how it fits together — without being overwhelmed by file lists or alternatives we ultimately rejected.

Consult the PR template

Read .github/PULL_REQUEST_TEMPLATE.md once before drafting. The template's required headers (today: ## Linked issue, ## Summary, ## Testing performed, ## Skill update, ## Checklist, ## Notes for the reviewer) must appear in the final body even when the skill's recommended structure below doesn't list them. Where the template and the skill overlap, use the template's richer header (e.g. ## Linked issue — with a Refs: link and any prerequisite-PR / follow-up-PR context — replaces the bare close-line at the top).

Required structure (in this order)

1. ## Linked issue — the template header, used instead of a bare close-line. The template asks for a GitHub issue here; a maintainer PR puts the Linear ticket in the same place: a single Refs [$TICKET_ID](https://linear.app/...) link, plus Fixes #N as well when a GitHub issue exists, plus links to any prerequisite or follow-up PRs and the Linear tickets they close. Keep it short — three lines max.

   ## Skill update — name the agent skill the change teaches. Reserve n/a — internal only for changes that are purely internal or a refactor with no user-visible delta; a user-facing change that teaches no existing skill still needs a sentence saying why no update is required. The template checklist asks you to confirm this section, so a body without it cannot tick that box truthfully.

2. ## At a glance — a copy-pasteable code sample from real code in the branch (not invented, not pseudocode) that demonstrates the change in user-observable terms. Below the code, one short sentence that grounds the "before" state if relevant.

   • The snippet must be small enough to absorb in 10 seconds but rich enough to convey what's new. Prefer a real call-site, contract emission, query, or output shape.
   • If the change is genuinely impossible to demonstrate in code (rare — even a refactor usually changes a signature), substitute a minimal representative diff or output sample. Do not open with abstract prose.
   • For PRs that ship a system rather than a behavior change (e.g. a new agent skill, a new CI gate, a new mechanism), the at-a-glance can show the artefact's eventual on-disk shape with a one-line note that the PR ships a placeholder. The point is grounding, not literal accuracy.

3. ## Decision (or ## The decision) — lead with what we decided. State the deliverable in one paragraph or a short numbered list. If the PR carries more than one substantive piece (e.g. a feature + an enabling framework change), enumerate them so the reader can't miss any. Link to ADRs inline at the points they matter.

4. ## How it fits together — the narrative, built bit by bit. 3–6 numbered steps that walk the reader from substrate to delivery. Each step should have a clear job (e.g. "lift the substrate", "add the codecs", "widen the operator surface", "prove against live infra"). Inline ADR links where relevant.

   • Multi-flow variant: if the system has multiple semi-independent flows (e.g. a user flow + an author flow + an enforcement mechanic), use multiple ## How X works subsections instead of one ## How it fits together. One subsection per flow, in the order a reader would learn the system.

5. ## Behavior changes & evidence — one bullet per observable change. Each bullet:

   • Leads with the change in plain, user-observable language.
   • Anchors to 1–3 implementation files (not all of them) using GitHub-friendly relative links.
   • Cites 1–2 evidence files (tests / fixtures / e2e).
   • Avoid dumping every file in the package. The change map should be distributed across these bullets, not pasted as a separate section.
   • System-design variant: if the PR ships a mechanism without yet shipping observable behavior (e.g. dormant CI gate, placeholder content), replace this section with ## What lands in this PR and a short commit-by-commit table (commit subject + one-line "what it adds"). Mention the AC count + link to the spec for the scoreboard; do not paste raw AC-IDs.

6. ## Reviewer notes (the gotchas) — strongly recommended. The 3–6 things you most expect a careful reviewer to push back on, surfaced proactively. Things that belong here:

   • Largest commit / largest diff and what to spot-check.
   • Decisions that look surprising on the diff but are deliberate (and why).
   • Pre-existing flakes / out-of-scope footnotes the reviewer will otherwise raise.
   • Pre-existing issues surfaced but not fixed in this PR; flagged as follow-up.
   • Project artefacts left on disk for review and their close-out plan.

   Place this near the top of the long-form sections — it's the most useful section to a skimming reviewer, so don't bury it after every other section.

7. ## Compatibility / migration / risk — SPI / API / behavioral compatibility notes. For small PRs, fold this into ## Reviewer notes instead of carrying it as its own section.

8. ## Verification (or ## Testing performed per the template) — list the suites you ran on the final HEAD, one per line, with the count of cases / tasks where useful. Note any flakes that reproduced and were ruled pre-existing.

9. ## Follow-ups — Linear tickets or doc notes for deferred work. Skip if there are none; don't pad.

10. ## Alternatives considered — final section. Each bullet names an alternative we genuinely weighed and why we didn't take it. Pull alternatives forward from any ADRs or design discussions so the reader doesn't have to click through. Frame as alternatives (decisions we made), not as "non-goals" (scope statements).

11. ## Checklist — the template's checklist, with each item marked [x] only if true. Common items: DCO sign-off, CONTRIBUTING.md read, tests updated, title in the prevailing convention.

Forbidden / discouraged patterns

• Don't open with abstract prose. The body opens with the Linear close line, immediately followed by ## At a glance and its concrete code sample. No "Intent" paragraph in between.
• Don't paste a "Change map" section near the top that lists every file. File links belong distributed across the narrative steps and behavior bullets where they have context.
• Don't dump file paths in behavior bullets. Each bullet gets at most ~3 implementation anchors and ~2 evidence anchors. If a section needs more, it's two changes — split the bullet.
• Don't bury major decisions inside other sections. If the PR carries a substantive framework change alongside a feature, the framework change must be enumerated in ## Decision so a reader can't skim past it.
• Don't conflate "non-goals" with "alternatives considered". Non-goals are scope statements ("we didn't ship X"); alternatives are decisions ("we considered X and chose Y because Z"). The PR ends with the latter.
• Don't include reviewer-coaching phrases ("anchor", "read this first", "tl;dr"). Write like a normal narrative.
• Don't paste auto-generated review-tool comments in the body you author. They're appended automatically by bots after creation.