/open-pr

name: open-pr
description: "Open a pull request that follows the repo's conventions. Reads the PR template from .github/PULL_REQUEST_TEMPLATE.md, fills it with contextualized content (not enumerations), links tracker tickets, writes testing notes, and uses /flagrare:write-docs style for the description. Use when the user says 'open a pr', 'create pr', 'push and pr', 'submit this', 'open pull request', or any variation. Also triggers when code is ready to ship and the user wants to get it reviewed."

Open PR

Create a pull request that reads like a human wrote it.

The goal is a PR description that a reviewer can scan in 30 seconds and understand: what changed, why, and how to verify it works. No file-by-file enumerations. No bullet-point dumps of every touched line. Context and narrative, and short: about 150 words for a small PR, 300 for a large one (the length gate in Step 4 enforces it). When a person can see the change, the body shows it: one before/after image.

**REQUIRED BACKGROUND:** Invoke `/flagrare:write-docs` before writing the PR body. A PR description is a tiny how-to/explanation doc, and the same craft applies: lead with the reader's situation, let prose carry causality, put context at the point of need. This skill owns *the PR mechanics and the repo's conventions*; write-docs owns *making the prose readable*. The "Writing style" section below applies that craft specifically to PRs, read both.

---

Workflow

Step 1: Understand what happened

Gather the raw material:

git log --oneline $(git merge-base HEAD main)..HEAD
git diff --stat $(git merge-base HEAD main)..HEAD
git diff $(git merge-base HEAD main)..HEAD

Also check the branch name for a ticket key (e.g., `SKU-478/fix-menu-disabled`).

Step 2: Learn the repo's conventions

A template tells you the *sections*; recently merged PRs tell you the *structural conventions* the template can't encode, the title prefix format, which section headings the team uses, how they link tickets and designs, what labels they apply. Read both for that skeleton only.

# The template (the section contract, follow it exactly)
cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null \
  || cat .github/pull_request_template.md 2>/dev/null \
  || ls .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null

# The lived convention: how this team actually writes PRs
gh pr list --state merged --limit 5 --json number,title,body 2>/dev/null

Borrow the team's **skeleton**: section names, title format, ticket-linking convention, labels. Match those exactly.

**Do NOT imitate their level of detail, and do NOT copy enumeration.** This is the trap that produces bad PR descriptions. Most teams' merged PRs are file-by-file changelogs, a `## Changes` section with a bullet per file, per function, or per internal symbol (`Added getFooHelper`, `Migration 0011`, `service now returns shipId`). That is exactly the style to avoid. The existing PRs being enumerated does not make enumeration the house style you should match, it makes it the habit this skill exists to break. Take the section *headings* from the recent PRs and fill them with context-first prose per Step 4, no matter how enumerated the existing PRs are.

If no template exists, use a minimal structure (title, description, testing notes) with the section headings the recent PRs use. Follow the template's section contract exactly; just never inherit its enumeration.

Step 3: Fetch linked context

If a ticket key was found (branch name, commit messages, or user-provided):

1. Fetch the ticket via the best available tool (MCP for the tracker platform, CLI, or WebFetch). Use the same detection logic as `/flagrare:intake` Step 0. 2. Use the ticket's title, description, and acceptance criteria to explain the "why" in the PR description.

If a design link (Figma, etc.) appears in the ticket, note it in the PR for visual reference.

Step 4: Write the PR body

**The hard rule, before anything else:** the description explains *what changed, why, and how to verify it*, in prose. It is never a list of files, functions, migrations, or internal symbols, the diff already shows those. If you find yourself writing "added X helper, updated Y service, changed Z schema", stop: that is the diff talking, not you. If you cannot describe the change without listing the files it touched, you do not yet understand it well enough to write the PR, go back to the diff and find the one or two sentences that explain what it actually does for someone.

**Length is a gate, not a guideline.** Count the prose only (not image tags or link URLs): about 150 words for a small or single-purpose PR, about 300 for a large one. One or two sentences per template section is normal. Write the short version first; writing long and trimming leaves the long version's shape behind. The usual overruns are a testing paragraph that lists every id, value and command; a code paragraph that re-argues decisions nobody asked about; and restating the ticket. The ticket and the diff carry the detail, so link them. Field-tested the hard way: an admin-service PR went out at 471 words for a two-field form change and the user had to ask for it to be cut. The same correction had already come up twice on earlier PRs.

**Show before and after for anything a person can see.** When the PR changes something visible (a page, a dialog, an email, a report, CLI output), the body includes one image with the old state above the new one, captured from dev or local, never production customer data. Crop each half to the part that changed and label the halves. If no "before" can be captured, say so and show the "after". Backend-only changes skip this unless an observable output (a response, a log line) makes the change obvious faster than prose. Upload images through GitHub before the PR exists: drop the file into the comment box of any open PR or issue in the same repo, copy the `user-attachments` URL it produces, clear the box without posting, and em