create-pr

---
name: create-pr
description: 'Use when the user asks to open, create or update a pull request or write its description, in any repository: "open a PR", "write the PR body", "сделай PR". Writes a scannable body under 20 lines: problem, solution, related PRs, a mermaid diagram of user flows, data changes with diagrams, new command input and output, reused code, packages picked and generator commands. Then creates or updates the PR with gh.'
---

# Create a pull request

The user's request MUST pick one of two modes:

- **Describe only**: the agent MUST draft the title and body, show them, and
  stop there.
- **Create or update**: the agent MUST draft them, then run `gh`. "Make a PR"
  MUST count as this mode.

## 1. Collect the facts

Guessing what the change does MUST NOT happen. The agent MUST read the diff:

```bash
git rev-parse --abbrev-ref HEAD                  # current branch
git log --oneline "$base"..HEAD                  # commits on this branch
git diff --stat "$base"...HEAD                   # files touched
git diff "$base"...HEAD                          # the actual change
GH_PAGER=cat gh pr view --json number,title,body # PR already open?
```

`$base` stands for the branch this one was cut from. The agent MUST find it
once:

```bash
remote=$(git remote | grep -qx origin && echo origin || git remote | head -1)
base=$remote/$(GH_PAGER=cat gh repo view --json defaultBranchRef \
  -q .defaultBranchRef.name)
```

Most repos call the remote `origin`, but a fork or a mirror can differ. The
name MUST be read from git rather than typed.

The agent MUST look for these too:

- A PR template, in `.github/pull_request_template.md` or under
  `.github/PULL_REQUEST_TEMPLATE/`, MUST be used when present.
- The commit and PR rules of the repo MUST be read: `CONTRIBUTING.md`,
  `AGENTS.md`, `CLAUDE.md`.
- An issue id in the commits or the branch name (`PROJ-123`, `JIRA-123`, `#42`)
  MUST be picked up.

Where the repo rules and this skill disagree, the repo rules MUST win. A
template MUST keep the parts it requires (checkboxes, headings), with the
sections below placed inside it.

## 2. Title

The title MUST match the repo's commit convention. The usual ones MAY be an
issue id prefix, `PROJ-123: add page pattern examples`, or conventional
commits, `feat(auth): add page pattern examples`.

Without a convention, the title SHOULD be one short imperative sentence on what
the change does, leaving out how.

## 3. Body

The `writing-style` skill MUST be loaded before the first line, as section 4
describes.

When a Jira ticket exists for this change, its name MUST sit alone on the
body's first line, ahead of the sections: `PROJ-123`. The name MUST go without
a link. The agent SHOULD look in the branch name or the commits, MUST ask when
both lack it, and MUST drop the line when no ticket exists.

The sections MUST follow in the order below. Some are conditional:

- **`Related PRs`** MUST appear only when the change builds on or goes with
  another PR.
- **`Data changes`** MUST appear only when the diff adds or changes a database
  object.
- **`Try it`** MUST appear only when the change adds or changes a command.
- **`Sources`** MUST appear only when the work drew on something outside the
  repo.
- **`Generated by commands`** MUST appear only when a command wrote or rewrote
  files in the diff.

The prose MUST stay under 20 lines, not counting the diagrams and command
blocks. Its reader is on a phone, in a notification, and hasn't opened the diff.
The body MUST follow this template:

````markdown
## What problem this solves

<Who was hurting and how. One or two sentences, the symptom a person could see,
not the internals. Three symptoms or more go in bullets instead.>

## How it works now

<What the change does, in order. Two to five bullets, one line each. Each one
opens with its point in bold, then the behaviour. The file name only if it
helps.>

## Related PRs

- [<owner/repo#123>](url): <what this PR needs from it, or it from this PR>

## User flow

**Before**

```mermaid
flowchart LR
  <the flow as it was, nodes coloured by status>
```

**After**

```mermaid
flowchart LR
  <the flow as it is now, same node IDs>
```

Green new, amber changed, red removed, gray unchanged.

## Data changes

<One bullet per table: what was added, dropped or changed.>

```mermaid
erDiagram
  <the changed tables and the tables their keys point at>
```

```mermaid
flowchart LR
  <Before and After pair: the trigger, the step that writes, the table>
```

## Try it

```console
$ <the exact command, with real arguments>
<the output to expect>
```

## Sources

- [<what it is>](url): <what the change took from it>

## Reused code and packages

<What the change reuses from this repo, one line each: the name, where it sits,
what it does here. Then every dependency it adds: the name, what it does, its
size. Then the packages you looked at and turned down, with the reason. No new
package? Write "No new packages." and, if a well known package would have fit,
say why you wrote it by hand instead.>

## Generated by commands

<Which part of the diff came out of the commands below, in one line, so the
reviewer reruns them instead of reading it.>

```bash
# <the files this command wrote>
<the exact command, run from the repo root>
```
````

A bullet MUST end within two lines. Past the cap, the agent SHOULD drop a
bullet and leave the wording alone.

### User flow

The diagram MUST trace the paths a person follows through the change. GitHub
draws the `mermaid` block as an image. Each flowchart MUST come as a Before
and After pair coloured by status:
[references/diagrams.md](references/diagrams.md).

- Every path the change adds or alters MUST appear. Paths it leaves alone MUST
  stay out.
- Each node MUST be a screen or an action, in plain words: "Picks a photo",
  "Sees the size error". File and function names MUST stay out.
- An error, cancel or retry branch MUST get an arrow of its own with a label:
  `-->|over 25 MB|`.
- One diagram SHOULD hold ten nodes at most. A larger change SHOULD get a
  diagram per flow.
- A label holding brackets, quotes or a colon MUST be wrapped in double quotes,
  or GitHub can't render the block.

With no person involved, like a CI job or a migration, the diagram MUST show
the trigger and the result.

### Related PRs

Any PR this change builds on, copies from, waits on or has to ship alongside
MUST get a link, in this repo or elsewhere. The reviewer can't judge the diff
without it. With no related PR, the section MUST be left out, and no "None" line
either.

- The agent SHOULD look in its own session first, then the branch this one was
  cut from, the ticket links and the commit messages.
- Each line MUST hold the full URL, so the link still works from another repo.
- Each line MUST name the tie between the two: "builds on its `formatBytes`",
  "the API side of this change", "copies its retry logic".
- When a merge order exists, it SHOULD be given: "merge after", "ship together".
- A URL MUST NOT be invented. When the agent knows of a PR but can't find it,
  it MUST ask the user.

The lines SHOULD read like this:

```markdown
- [acme/api#412](https://github.com/acme/api/pull/412): adds the 25 MB limit this page reads. Merge it first.
- [acme/web#87](https://github.com/acme/web/pull/87): same upload fix for the old page, this PR copies its error text.
```

### Data changes

Database objects are tables, columns, keys, indexes, constraints, views, enums
and stored procedures. They turn up in migrations, `*.sql`, schema files and ORM
models. A diff without one MUST leave the section out.

- **Tables** every table added or changed MUST get a bullet: the name in bold,
  then the columns added, dropped or renamed, with type and nullability.
- **Relations** the `erDiagram` MUST include each changed table and every table
  a changed key points at. A new column MUST get a `"new"` comment.
- **Data flow** the `flowchart` MUST trace how data gets to each changed table:
  the trigger, the step doing the write, then the table as a node.
- **Writes** an arrow into a table SHOULD be labelled: `-->|insert|`,
  `-->|update|`, `-->|delete|`.
- **Backfill** a migration that fills or moves existing rows MUST get a path of
  its own.

### Try it

This section MUST cover a command that is new or changed: a CLI, a script, a
`package.json` script, a Make target, a slash command, a new flag.

- The agent MUST give the exact line a person types, with real arguments, then
  its output.
- When the command is local and safe, the agent SHOULD run it and paste the
  real output, cut down to the lines a person looks at.
- A command that needs secrets or touches shared systems MUST NOT be run. The
  agent MUST work out the output from the code and put `# expected, not run`
  above it.
- A command that validates its input SHOULD also show one bad input and the
  error it gives.

The section SHOULD read like this:

```console
$ todo add "Buy milk" --due friday
Added #14 "Buy milk", due Fri 10 Oct
$ todo add ""
error: the title is empty
```

### Sources

Each resource outside the repo that shaped the change MUST get a link: a Figma
frame, a Confluence page, an API doc, a Slack thread, an issue in another repo.
The reviewer holds the code up against it.

- The link SHOULD land on the exact spot: the Figma frame with its `node-id`,
  the heading in the doc, the Slack message.
- Each line MUST name what the change took from it: the error text, the
  spacing, the rate limit.
- The agent SHOULD look in the ticket's links and attachments, its own session,
  the commit messages and the comments in the diff.
- A URL MUST NOT be invented. When the agent used a source but lost it, it MUST
  ask the user for the link.
- The Jira ticket MUST go on the body's first line, outside this list.
- The spec the branch adds or extends under `specs/` SHOULD come first in this
  list, linked to the file on the branch.
- A pull request MUST go under Related PRs, outside this list.

The lines SHOULD read like this:

```markdown
- [Upload error, Figma](https://www.figma.com/design/AbC123/Uploads?node-id=12-345): the error text and its red.
- [Upload API, Confluence](https://acme.atlassian.net/wiki/spaces/API/pages/123456): the 25 MB limit.
```

### What belongs in Reused code and packages

Reused code MUST come first, packages after.

**Reused** is code already in the repo before this branch that the change now
calls: a helper, a component, a hook, a service, a type. It MUST be listed.

- The agent SHOULD spot it in the imports and calls the diff adds. Code outside
  the files the branch created counts:
  `git diff --diff-filter=A --name-only "$base"...HEAD`.
- Each line MUST give the thing, its location and its job here.
- The list SHOULD end at five. It SHOULD lead with what a reviewer would expect
  to see written from scratch.
- When the reused code is too minor to name, the reused lines MAY go.

**Packages** is third party code the change now depends on, or would have. A
new peer or dev dependency MUST count too.

Both lists MUST leave out the repo's own tooling: Vitest, Nx, the linter. The
same MUST go for MCP servers, editors and agents. A command that wrote code
MUST go under Generated by commands.

The diff MUST be checked before any line about packages. A package missing from
the manifest MUST NOT be claimed:
`git diff "$base"...HEAD -- '**/package.json' 'package.json'`.

Each rejected package MUST give its reason in a few words: size, unmaintained,
its licence, it pulls in a lot, the repo already covers it, or a hand-written
version takes ten lines.

- A reused line MAY read: "Reuses `formatBytes` from `src/utils/format.ts` to
  print the limit."
- A new package MAY read: "`date-fns` 3.6, 2 kB after tree shaking, formats
  the due dates."
- A rejected package MAY read: "Turned down `moment`: 70 kB and no tree
  shaking."
- No new package MAY read: "No new packages. `lodash.groupby` would have done
  it, but `Object.groupBy` ships in every browser we support."

### Generated by commands

A command MUST go here when it wrote or rewrote files that are in the diff: a
generator, a codemod, a `sed` or `ast-grep` rewrite, a schema or API client
generator, `pnpm add` changing the lockfile, `vitest -u` writing snapshots.

- Each command MUST be the exact line, with real arguments, in the order the
  agent ran them. The reviewer runs it again and diffs the output.
- Each command SHOULD have a comment above it naming the files it wrote.
- A generated file later edited by hand MUST be named, or the reviewer passes
  over it as generated.
- Commands that only read or check MUST be left out: `git`, `grep`, tests, a
  build whose output isn't committed.

The agent SHOULD search its own session first, the commit messages next, the
diff last: a "generated" header, a lockfile, a snapshot. A command the agent
can't reconstruct MUST NOT be invented, and the agent MUST ask the user. The
block SHOULD read like this:

```bash
# libs/upload/** and its path in tsconfig.base.json
pnpm nx g @nx/js:library upload --directory=libs/upload
# every getSize call under apps/web
ast-grep run -p 'getSize($A)' -r 'formatBytes($A)' -U apps/web
```

## 4. How to write it

The `writing-style` skill MUST be loaded first, from `writing-style/SKILL.md` in
this skills folder. It carries all the wording rules and the checklist to run
before posting, and its "Shape on the page" section decides the layout. The
agent SHOULD load it once, unless it is already in context.

Only these rules are specific to the PR body, and each MUST hold:

- It MUST make sense on the first read, to a reader with zero context on this
  codebase.
- The section heading already names the section, so the line below it MUST
  open with the fact.
- The change MUST be described and the effort MUST NOT: what the code does now,
  no counts of lines or files, no "refactored". How the code got written MUST
  go only under Generated by commands.
- A guess MUST be marked as a guess.

The agent MUST read the body once more before posting, and every word the
reader can do without MUST go.

## 5. Create or update the PR

Every `gh` call MUST start with `GH_PAGER=cat`, or a pager opens and the run
hangs.

When the branch has no upstream, the agent MUST push it first:

```bash
git push -u "$remote" HEAD
```

For a new PR the agent MUST run:

```bash
GH_PAGER=cat gh pr create --base <base> --title "<title>" --body-file <file>
```

The body MUST go in a temp file instead of inline, so the newlines and
backticks come through.

For an existing PR the agent MUST run:

```bash
GH_PAGER=cat gh pr edit --title "<title>" --body-file <file>
```

`--draft` MAY be added only when the user asked for a draft.

Right after a rebase or force push, `gh pr view --json mergeable` can show a
conflict that is out of date. Any edit refreshes it, so the agent SHOULD ask
again once when the answer looks off.

## 6. Report back

The agent MUST give the PR link and the title, in one or two lines, and stop
there.

## Guardrails

- A push or a PR on the default branch or a protected one MUST NOT happen. The
  agent MUST stop and report it.
- The problem statement MUST NOT be made up. When the diff doesn't show why the
  change exists, the agent MUST ask the user one question.
- A force push, an amend of published commits and `--no-verify` MUST NOT
  happen.
- Staged or untracked files unrelated to the change MUST stay as they are.

## Example body

A finished body SHOULD read like this:

````markdown
PROJ-123

## What problem this solves

Uploading a photo over 5 MB failed with a blank screen. People retried the same
file several times and then gave up, so support got about 30 tickets a week.

## How it works now

- **Cap** files up to 25 MB upload. The old cap was 5 MB.
- **Too big** the error names the limit and the file's own size, so the person
  knows what to do next.
- **Double submit** the upload button stays disabled while a file is in flight.

## User flow

**Before**

```mermaid
flowchart LR
  A(Picks a photo):::same --> B{Size}:::changed
  B -->|up to 5 MB| C(Upload starts):::changed
  C --> D(Sees the photo in the list):::same
  B -.->|over 5 MB| E(Sees "Upload failed"):::removed
  classDef new fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#111827
  classDef changed fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#111827
  classDef removed fill:#fee2e2,stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 3,color:#111827
  classDef same fill:#f3f4f6,stroke:#9ca3af,color:#111827
```

**After**

```mermaid
flowchart LR
  A(Picks a photo):::same --> B{Size}:::changed
  B -->|up to 25 MB| C(Upload starts, button disabled):::changed
  C --> D(Sees the photo in the list):::same
  B ==>|over 25 MB| E(Sees the limit and the file size):::new
  classDef new fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#111827
  classDef changed fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#111827
  classDef removed fill:#fee2e2,stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 3,color:#111827
  classDef same fill:#f3f4f6,stroke:#9ca3af,color:#111827
```

Green new, amber changed, red removed, gray unchanged.

## Data changes

- **`uploads`** new `size_bytes bigint not null`, filled from storage for old
  rows.

```mermaid
erDiagram
  users ||--o{ uploads : owns
  uploads {
    uuid id
    uuid user_id
    bigint size_bytes "new"
  }
```

**Before**

```mermaid
flowchart LR
  A(Person uploads a photo):::same --> B[Upload API]:::changed
  B -->|insert| T[(uploads)]:::changed
  classDef new fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#111827
  classDef changed fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#111827
  classDef removed fill:#fee2e2,stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 3,color:#111827
  classDef same fill:#f3f4f6,stroke:#9ca3af,color:#111827
```

**After**

```mermaid
flowchart LR
  A(Person uploads a photo):::same --> B[Upload API]:::changed
  B -->|insert| T[(uploads)]:::changed
  M[Migration]:::new ==>|"update size_bytes"| T
  classDef new fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#111827
  classDef changed fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#111827
  classDef removed fill:#fee2e2,stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 3,color:#111827
  classDef same fill:#f3f4f6,stroke:#9ca3af,color:#111827
```

Green new, amber changed, red removed, gray unchanged.

## Sources

- [Upload error, Figma](https://www.figma.com/design/AbC123/Uploads?node-id=12-345):
  the error text and the layout of both sizes.

## Reused code and packages

- Reuses `formatBytes` from `src/utils/format.ts` to print both sizes.
- `browser-image-compression` 2.0, 12 kB, shrinks a photo in the browser
  before it goes up.
- Turned down `sharp`: it only runs on the server, and the point here is to
  cut the upload before it starts.
- Turned down `filesize`: `formatBytes` already prints "25 MB".
````

• SKILL.md 18 KB
• references/diagrams.md 2 KB