| name | ripl-pull-requests |
| description | Write pull request titles and descriptions for the Ripl monorepo. Use whenever opening a PR, retitling one, or rewriting a PR body. Covers the sentence-style title convention (which is deliberately different from the conventional-commits style used for commit messages), what belongs in a description, and how to report verification honestly. |
Writing Ripl pull requests
Titles are sentences, not commit subjects
A PR title is a sentence describing the change. It is not a conventional-commit subject.
Size the canvas surface from the host, not the backing store
Keep the pointer origin current instead of snapshotting it once
Reuse resolved paint instead of rebuilding it every frame
Audit every rendering context against the base contract
Not:
fix(canvas,3d): size the surface from the host, not the backing store
perf(core)!: reuse resolved paint
Rules:
- Start with a capital letter and a verb in the imperative. No
type(scope): prefix, no trailing period.
- Say what the change does, in terms a reader who hasn't seen the diff can follow. Prefer
"Keep the traced path across paint and transform changes" over "Fix path cache invalidation".
- Name the thing that was wrong when it's the point of the PR. "…from the host, not the backing
store" carries the whole bug in five words; "Fix canvas sizing" carries none of it.
- Don't mark breaking changes in the title. Put a
## Breaking section at the end of the body.
Commit messages stay conventional
Commits keep the type(scope): subject format with a ! for breaking changes, per
CONTRIBUTING.md and AGENTS.md. The two conventions
coexist because main takes merge commits, not squashes — a PR title never becomes a commit
subject, so it is free to read as prose while the history stays machine-parseable.
Check before assuming: if the repository ever switches to squash merges, the PR title does become
the commit subject and this convention has to be revisited.
Commit bodies follow the house voice from AGENTS.md — extremely concise, grammar sacrificed for
concision. PR bodies do not: they are written for a human reviewer and should be readable prose.
What goes in the body
Lead with the problem, not the patch. A reviewer needs to know why the diff exists before they can
judge it.
- The problem. What is broken or slow, with the evidence — a code excerpt, measured numbers, a
before/after table. Quote the offending lines rather than describing them.
- The fix, and why this shape of fix. If you rejected an obvious alternative, say so and why;
that is usually the most useful paragraph in the PR.
- Verification. Which gates ran, and what the new tests actually pin. For a bug fix, state that
the regression test fails without the fix — a test that passes either way proves nothing.
- Breaking changes, in a
## Breaking section, naming the exact symbol and the migration.
- Follow-ups the PR deliberately leaves undone.
Keep it proportionate: a one-line fix does not need five headings.
Report verification honestly
State what you actually ran and what you could not:
- Name the real numbers (
yarn test 178 files / 2004 tests), not "tests pass".
- If a check in the plan could not be run in this environment, say so plainly and say what you
substituted. Never imply a measurement you did not take.
- The chart visual-regression baselines are rendered on a specific Linux Chromium and currently fail
on
main in the sandbox. Comparing against them proves nothing — instead render the gallery on
main and on the branch in the same environment and diff those, and say that is what you did.
Stacked PRs
When a branch depends on another, target the parent branch as the base and open with a line saying
so, so the reviewer knows the diff excludes the parent's commits:
Stacked on #59 — review that first; this PR's diff is only the paint-materialization commit.
Attribution
Every PR body, review, and comment ends with:
---
_Generated by [Claude Code](https://claude.ai/code)_
