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 each question again in full: what it is about, the options, and your recommendation. The user may not remember it, and "the open question" or a count of them gives nothing to 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.

Check mergeability

Check mergeability by exit status, before any step below. Run it alone and read the result before going on: chained to a later step, it stops nothing.

git fetch origin main &&
  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.

Before writing

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

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.

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.

Just before opening

Check mergeability again, as above: main moves while these steps run.

Then run mise run update-baselines and commit the update. This is the only step that updates the baselines. CI fails on any difference from either one: the stdlib coverage, a region a test now reaches included, and the fuel benchmarks. wado-compiler/lib/AGENTS.md says what the coverage baseline may change.

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.