Convention over configuration: pr-brief

The idea

A tool with many knobs gives you a different description in every repo. Reviewers have to relearn the format each time, the checks have to allow for every combination, and every team spends a meeting on node limits.

pr-brief takes the other road. It fixes the shape of the description and the size of a diagram, then offers only the choices that do not change what a reviewer sees: how the prose is edited, what happens to the earlier description, and how the diagrams look.

A rule changes in a plugin release, not in a config file. That keeps every PR that follows the convention comparable to every other one.

What is fixed

Rule	What is fixed
The PR title	Never changed. Only the description changes.
The parts	`## Brief`, `## Change map`, `## Review guide`, in that order.
The Brief	One paragraph of at most 5 sentences. Conceptual. No file names.
Diagrams	At most 3 diagrams per PR, one for each flow.
Nodes	At most 9 nodes in a diagram, context nodes included.
Edges	At most 14 edges in a diagram. The invisible layout links do not count.
Labels	At most 28 characters.
Context nodes	At most 2 context nodes in a diagram, one hop from changed code.
Read these first	1 to 7 rows, ranked by risk. A row you cannot justify is dropped.
Small PRs	A PR with 3 code files or fewer gets no diagram, and says why.
Length	At most 65,536 characters on GitHub, and at most 4,000 characters on Azure DevOps. The check counts characters, and takes the limit from the host the PR lives on.
Prose	Zero hard ASD-STE100 violations when the style is ste or ste+iceberg.
Diagram style	Produced by the tool from the theme. The gate recomputes it and compares it exactly.
The gate	Always on, and it always blocks.
Writing to a PR	Always asks first, and always shows a before and after.

The source of truth is the convention file and the constants in internal/convention. A test fails if this page disagrees with them.

What you can set

Setting	Values	Default
`style`	`ste+iceberg`, `ste`, `iceberg`: how the prose is edited	`ste+iceberg`
`improve.previous`	`drop` replaces the earlier description; `comment` keeps it as a hidden comment	`drop`
`diagram.theme`	`github-dark`, `github-light`, `dracula`, `alucard`, or a path to a theme JSON file	`github-dark`

Anywhere a setting can be written, the same order applies: a command-line flag, then the repo file, then your user file, then the default. CI reads only the repo file and the defaults. An unknown key is an error, so nothing else can creep in.

What you get in return

Every PR reads the same. A reviewer learns the layout once, in any repo that uses it.
The gate can be exact. With nothing to tune, it checks the structure, the limits and the whole diagram style, and a failure always says what to fix.
Nothing to argue about. Nobody debates whether a diagram may have twelve nodes. It may have nine, and the tool collapses the rest.
Diagrams that render. The limits and the layout fix come from testing on GitHub. A knob that breaks the layout would not be offered.
A short README. Three settings fit in one table.

What it costs

You cannot raise a limit. A PR that really needs ten nodes in one flow is shown at nine, with the rest folded into a +N more node. The Review guide lists what was folded.
You cannot rename a section or soften the gate to a warning.
A rule you disagree with waits for a release. You can open an issue, or fork the plugin.
Small PRs get less. Three code files or fewer get a brief and a review guide, but no diagram.

Ways out

Skip one PR. Put a visible line in the description: > pr-brief skipped: <reason>. The reason is required and stays readable to reviewers.
Make it your own look. A custom theme file changes every colour.
Choose the prose. style picks the ASD-STE100 rewrite, iceberg, or both.
Keep the old text. improve.previous: comment hides the earlier description in the PR instead of dropping it. A copy is always saved on your machine.

Standardizing a team

One file at the repo root makes everybody in the repo use the same settings: .pr-brief.json. It is committed, so a teammate gets it with the repo, and it wins over their personal settings.

pr-brief init --pr-template --workflow

# wrote  .pr-brief.json
# wrote  .github/pull_request_template.md
# wrote  .github/workflows/pr-brief.yml

.pr-brief.json holds the three settings. It never overwrites an existing file.
.github/pull_request_template.md shows contributors the structure, including people who do not use Claude Code.
.github/workflows/pr-brief.yml runs the check in CI. It reads the config from the base commit, so a PR cannot edit the rules that check it.

The repo’s style and theme are what the hook and CI enforce. The marker in a description cannot weaken them. If you want to set the theme for the whole team, run pr-brief config set diagram.theme dracula --scope repo and commit the file.

Changing a rule

Open an issue that says which rule and what it blocks you from doing. A change to a limit or a section is a new release with a note on what breaks. A new theme can be added without breaking anything.