---
name: pull-request
description: The rules for opening a PR you must read before creating or editing any pull request.
---

## First: a question you asked is a stop

If even one question you put to the user is still unanswered, stop here. Do not
open a pull request, do not edit one, do not write a title or a description.
End the turn by asking for the answer.

A pull request never goes out with an open question behind it. "The rest is
ready" is not a reason to proceed, and neither is a question that looks minor:
the user decides what is minor.

## Before writing

Read the branch's own changes, generated files left out:

```sh
git diff origin/main...HEAD -- $(scripts/changed-sources.sh)
```

The title and description come from that diff, not from the session that
produced it. `scripts/changed-sources.sh` drops what `.gitattributes` marks
`linguist-generated` or `linguist-vendored`, which is where a regenerated corpus
or a fetched one would otherwise bury the change the PR is actually about. Say
in the description that the generated output was regenerated, not what moved
inside it.

Revise the branch while you are there: clean up comments and docs according to
the project rules.

Check mergeability by exit status (after `git fetch origin main`):

```sh
git merge-tree --write-tree --no-messages --name-only HEAD origin/main
```

Exit 0 = mergeable; exit 1 = conflicts, printing the merged tree OID followed
by one conflicted path per line. This runs the real (ort) merge in memory and
touches neither the worktree nor the index.

If conflicting, resolve with the `git-upstream-sync` skill.

## Title

A short summary of the value the branch creates, not of what was edited. A
reader scanning a list of PRs is deciding whether to care.

`<type>(<scope>): <the value>`

If the branch is worth more than one thing, name the largest and leave the rest
to the description.

`type` is one of these, with `!` for a breaking change. The scope is optional.
`.claude/hooks/pr-conventions.mts` reads the types from this list.

- `feat`
- `fix`
- `docs`
- `perf`
- `refactor`
- `chore`

## Description

Open with the outcome, in a paragraph a reader can stop after: what holds once
this is merged, and what it is worth. Mechanism comes after, under headings.

Do not include trial-and-error history in the description; the commit history is
the SSoT. That is any sentence which only parses against the pre-branch state:
"previously X, now Y", "an earlier approach", "X was replaced by Y", a count
given as a delta ("2 -> 0"). Read each sentence back and ask whether it works
for someone who sees only the merged tree. If it needs the old state, cut it.

- No: "Codegen looked the global up by name; it now compares the read's type."
- Yes: "Codegen compares the read site's `result_ty` against the slot's type."

The opening paragraph is the hardest place to hold that line: a speedup is worth
stating, the struggle to find it is not.

If the branch obviously closes a known issue, add a closing keyword
(`Closes #N`). Do not go looking for one to attach.

No need to include a test section. CI runs the full test suite.

Angle brackets need nothing but a code span: `` `t_<Name>` `` renders as
written. The GitHub MCP server drops them and HTML-escapes quotes in the text it
reads back. Check the web UI before believing the description is broken, and
never rewrite prose to work around it.

Cut the draft before posting. A first draft follows the shape of the work: a
heading for each thing that happened, at the length it took to do. Read it back
and cut every sentence a reader would skip.

## After opening

Subscribe to the PR with `subscribe_pr_activity`. Handle every event it
delivers; skipping one is a decision you state.

If the tool is unavailable, check the PR status and its review comments every
10 minutes instead. Stop once the review has settled and CI passes.

Keep checking mergeability (`mergeable_state`). If conflicting, resolve it with
the `git-upstream-sync` skill.

Answer a review, human or bot, with the `code-review-response` skill.