pr-standard — house PR bodies
Every pull request carries a filled template, a diagram, and four labels. The prose follows
ASD-STE100 (Simplified Technical English). This is a hard rule for humans and for agents.
Overview
- Six writing rules. One idea per sentence. The same word for the same thing. Active voice.
Imperative in steps. No filler. Exact technical names.
- Fill the template. A PR body has Summary, How It Works, Linked issues, Testing evidence, and
Notes. Never replace it with one paragraph.
- One diagram, always. Embed a mermaid block that shows the mechanism this PR changes.
- Four labels. Type,
priority:*, t-shirt:*, and area:*.
- Write the body in a forked chat. The conversation that wrote the code writes for itself.
- Length is whatever the reviewer needs. STE100 makes the text clear. It does not cap the length.
Hard rule for agents
Do not run gh pr create -b "<one paragraph>". Fill the template. Write the body to a file, then
pass the file:
gh pr create --title "feat(api): add phone to leads" --body-file /tmp/pr-body.md \
--label enhancement --label priority:high --label t-shirt:small --label area:api
Use gh pr edit <number> --body-file <file> to correct a body that is already open.
The six writing rules
| Rule |
Do this |
Not this |
| One idea per sentence |
"The endpoint reads lead_id. It returns 404 when the row is absent." |
"The endpoint reads lead_id and returns 404 when the row is absent, which also covers the deleted case." |
| Same word for the same thing |
client everywhere |
client, customer, account in one PR |
| Active voice |
"The migration adds core.leads.phone." |
"core.leads.phone is added by the migration." |
| Imperative in steps |
"Run pnpm test." |
"You will want to run pnpm test." |
| No filler |
"The view needs a base-table grant." |
"Basically the view just needs a base-table grant in order to work." |
| Exact technical names |
public.processes, service_instance_id |
"the processes view", "the instance id" |
Banned filler words: basically, simply, just, actually, in order to, obviously, of course.
Pick one noun per concept and hold it for the whole PR. Read the repo's CLAUDE.md for a project
noun list before you invent one.
The four labels
Set all four on every PR. Read labels for the full table.
| Slot |
Values |
| Type |
bug, enhancement, or documentation |
| Priority |
priority:critical, priority:high, or priority:medium |
| Size |
t-shirt:small, t-shirt:medium, or t-shirt:big |
| Area |
that repo's existing area:* labels |
Area names are per repo. Run gh label list --limit 100 and pick from the result. Do not invent
an area:* label. When the repo carries no area:* label, set the other three and say so in the PR.
Read the label list before you post. gh pr create rejects the whole command when any --label
does not exist, and it does so after the branch is pushed. The priority scale is per repo too — some
carry priority:low, others stop at priority:medium. Never assume a scale from another repo, and
never create a label inside a feature PR. Commands and the failure mode: labels.
Documentation
- Writing rules — the six rules, banned words, worked rewrites
- Body template — the section shape, plus a copy-paste skeleton
- Labels — the four-pack, discovery commands, and label creation
- Diagrams — which diagram a change needs, and the three mermaid traps
- Forked chat — the five-step workflow that produces the body
Common workflows
Open a PR. Finish the code. Fork the chat. Hand the fork the diff summary, the diagram text, and
the linked issues. The fork fills the template, checks the mermaid, and runs gh pr create --body-file. Drop the fork.
Fix a thin body. Read the diff with gh pr diff <number>. Rewrite the body against the template.
Run gh pr edit <number> --body-file <file>.
Label an existing PR. Run gh label list --limit 100. Map the change to the four slots. Run
gh pr edit <number> --add-label <label>.
Scope
- New pull requests follow this card.
- Old open pull requests are not rewritten for the standard alone.
- When you edit an old body for another reason, bring it up to the standard while you are there.
Repo-local rules win
A repo can add rules on top of this card — a required ERD, a diagram index, a CI check, an agreed
noun list. Read its CLAUDE.md and .github/pull_request_template.md first. This card is the floor,
not the ceiling.
1---2name: pr-standard3description: House standard for GitHub pull request descriptions. Use when opening or editing a pull request, running gh pr create or gh pr edit, writing or rewriting a PR body, or setting labels on a PR. Triggers on mentions of PR description, pull request body, gh pr create, gh pr edit, PR template, PR labels, priority label, t-shirt label, area label, ASD-STE100, Simplified Technical English, PR diagram, mermaid in a PR.4---56# pr-standard — house PR bodies78Every pull request carries a filled template, a diagram, and four labels. The prose follows9**ASD-STE100 (Simplified Technical English)**. This is a hard rule for humans and for agents.1011## Overview1213- **Six writing rules.** One idea per sentence. The same word for the same thing. Active voice.14 Imperative in steps. No filler. Exact technical names.15- **Fill the template.** A PR body has Summary, How It Works, Linked issues, Testing evidence, and16 Notes. Never replace it with one paragraph.17- **One diagram, always.** Embed a mermaid block that shows the mechanism this PR changes.18- **Four labels.** Type, `priority:*`, `t-shirt:*`, and `area:*`.19- **Write the body in a forked chat.** The conversation that wrote the code writes for itself.20- **Length is whatever the reviewer needs.** STE100 makes the text clear. It does not cap the length.2122## Hard rule for agents2324Do not run `gh pr create -b "<one paragraph>"`. Fill the template. Write the body to a file, then25pass the file:2627```bash28gh pr create --title "feat(api): add phone to leads" --body-file /tmp/pr-body.md \29 --label enhancement --label priority:high --label t-shirt:small --label area:api30```3132Use `gh pr edit <number> --body-file <file>` to correct a body that is already open.3334## The six writing rules3536| Rule | Do this | Not this |37|---|---|---|38| One idea per sentence | "The endpoint reads `lead_id`. It returns 404 when the row is absent." | "The endpoint reads `lead_id` and returns 404 when the row is absent, which also covers the deleted case." |39| Same word for the same thing | `client` everywhere | `client`, `customer`, `account` in one PR |40| Active voice | "The migration adds `core.leads.phone`." | "`core.leads.phone` is added by the migration." |41| Imperative in steps | "Run `pnpm test`." | "You will want to run `pnpm test`." |42| No filler | "The view needs a base-table grant." | "Basically the view just needs a base-table grant in order to work." |43| Exact technical names | `public.processes`, `service_instance_id` | "the processes view", "the instance id" |4445Banned filler words: **basically, simply, just, actually, in order to, obviously, of course**.4647Pick one noun per concept and hold it for the whole PR. Read the repo's `CLAUDE.md` for a project48noun list before you invent one.4950## The four labels5152Set all four on every PR. Read [labels](docs/labels.md) for the full table.5354| Slot | Values |55|---|---|56| Type | `bug`, `enhancement`, or `documentation` |57| Priority | `priority:critical`, `priority:high`, or `priority:medium` |58| Size | `t-shirt:small`, `t-shirt:medium`, or `t-shirt:big` |59| Area | that repo's existing `area:*` labels |6061**Area names are per repo.** Run `gh label list --limit 100` and pick from the result. Do not invent62an `area:*` label. When the repo carries no `area:*` label, set the other three and say so in the PR.6364**Read the label list before you post.** `gh pr create` rejects the whole command when any `--label`65does not exist, and it does so after the branch is pushed. The priority scale is per repo too — some66carry `priority:low`, others stop at `priority:medium`. Never assume a scale from another repo, and67never create a label inside a feature PR. Commands and the failure mode: [labels](docs/labels.md).6869## Documentation7071- **[Writing rules](docs/writing-rules.md)** — the six rules, banned words, worked rewrites72- **[Body template](docs/body-template.md)** — the section shape, plus a copy-paste skeleton73- **[Labels](docs/labels.md)** — the four-pack, discovery commands, and label creation74- **[Diagrams](docs/diagrams.md)** — which diagram a change needs, and the three mermaid traps75- **[Forked chat](docs/forked-chat.md)** — the five-step workflow that produces the body7677## Common workflows7879**Open a PR.** Finish the code. Fork the chat. Hand the fork the diff summary, the diagram text, and80the linked issues. The fork fills the template, checks the mermaid, and runs `gh pr create81--body-file`. Drop the fork.8283**Fix a thin body.** Read the diff with `gh pr diff <number>`. Rewrite the body against the template.84Run `gh pr edit <number> --body-file <file>`.8586**Label an existing PR.** Run `gh label list --limit 100`. Map the change to the four slots. Run87`gh pr edit <number> --add-label <label>`.8889## Scope9091- New pull requests follow this card.92- Old open pull requests are not rewritten for the standard alone.93- When you edit an old body for another reason, bring it up to the standard while you are there.9495## Repo-local rules win9697A repo can add rules on top of this card — a required ERD, a diagram index, a CI check, an agreed98noun list. Read its `CLAUDE.md` and `.github/pull_request_template.md` first. This card is the floor,99not the ceiling.
zot24