open-a-pr git:20260921.bbe08f8A

Immutable. This exact content is served forever at /api/v1/blob/5b416f10e14ea29f.

---
name: open-a-pr
description: Open a PR, write or rewrite a PR description, "the PR body is too long", or check whether a PR description is readable. Use whenever a PR is created or its body is edited.
---

# Skill: Open a PR

A PR body is read in thirty seconds, before the diff. It answers four
questions and stops. Everything else lives in the commit messages, the spec,
and the report CI posts.

## The shape

`.github/pull_request_template.md`. Fill every heading; add none. Under ~200
words total.

```markdown
## What is this about?
One or two sentences, plain words: the surface and the change.

## What problem does it solve?
The pain a person felt or the risk we carried. Not the mechanism.

## What was the situation before?
What the person saw or could not do. Concrete enough to recognise in the
"before" screenshot.

## Evidence
The spec that proves it, and in one line what its before → after shows.
```

Title: conventional commit, imperative, under 70 characters.

## Evidence

CI runs every spec the PR changes on the PR head and posts one sticky
`<!-- test-evidence -->` comment linking the report. You never run the
publisher or attach screenshots by hand. The body names the spec and says
what the reader will see; it does not copy verdicts, SHAs, screenshots or
links, which go stale.

```markdown
## Evidence
`evals/specs/browser-tabs-owned-by-thread.e2e.test.ts` — before: the toolbar
shows Suspend; after: it does not, and a page still opens and can be used.
```

- The `before:` here and "What was the situation before?" are the same
  moment. If they disagree, fix one.
- No spec changed? Say why in one line: `No E2E; unit-tested` or
  `node --test .github/scripts/pr-proof.test.mjs — 6 passed`. If no evidence
  comment appears, that is why; do not run a spec locally and paste its output.
- Red evidence needs no sentence in the body: CI's comment says Failed on
  that SHA and flips on its own when the head goes green. Fix the spec or the
  code; do not narrate the verdict.
- Evidence binds to a commit. After a rebase or cherry-pick, wait for CI to
  rerun on the new head; do not cite the old comment.
- UI changes: one trailing line `Design: P3, S4, C6` (DESIGN.md rule ids).

## Leave out

Root-cause narrative (commit message). Suite counts and CI matrices (the
Required verification check). Image digests, worktree setup, credential
notes (the spec's world). Other PRs' failures (an issue). Risk, Rollback,
Out-of-scope boilerplate. Caveats about your caveats.

## Do it

```bash
gh pr create --base dev --title "<type>(<scope>): <change>" --body-file /tmp/pr-body.md
gh pr edit <n> --body-file /tmp/pr-body.md
```

Write the file first and read it as the reviewer would. If a section makes
you scroll, cut it.