Pull requests are too dense for a person to read: review how Braid writes them #570

Closed
opened 2026-11-20 15:07:01 -05:00 by cmoriarty · 1 comment
Owner

What happens

cmoriarty/sports-breaker#200 runs to 1,249 words:

  • The title is the first bullet, cut off: A site row whose opponent is a placeholder ("TBD", "TBA", "to be…
  • "What was done" is eight sentences of about 50 words.
  • The code review is nearly half the page: six fixes already made, six minor notes left alone.
  • What went unchecked is spread over three sections; "no CI ran" is near the bottom.
  • Braid's terms throughout: unit lane, judge, test lint, step allowance.
  • The run link is an internal address, on a public repository.

Why

A pull request is for the person in the loop; this one reads like the run's log. The brief caps a bullet at one sentence, not a length, and code adds the rest a section at a time. braid#38 trimmed it once; it grew back.

Fix

Review each part for who reads it and why. Then:

  • A title saying what changed, in plain words.
  • On top, a minute's read: what changed, what wasn't checked or needs a decision, how to try it.
  • The rest folded away, or left to the merge gate (braid#548).
  • No Braid terms.

Done when

That pull request, rewritten this way, reads in a minute and the owner prefers it. The next run's comes out the same way.

Where to look: build_summary (src/osf/engine/prompts.py); _title, _pr_body (src/osf/forgejo.py); spec pull-request-description.

From the owner reading that pull request, 2026-11-20.

**What happens** cmoriarty/sports-breaker#200 runs to 1,249 words: - The title is the first bullet, cut off: `A site row whose opponent is a placeholder ("TBD", "TBA", "to be…` - "What was done" is eight sentences of about 50 words. - The code review is nearly half the page: six fixes already made, six minor notes left alone. - What went unchecked is spread over three sections; "no CI ran" is near the bottom. - Braid's terms throughout: unit lane, judge, test lint, step allowance. - The run link is an internal address, on a public repository. **Why** A pull request is for the person in the loop; this one reads like the run's log. The brief caps a bullet at one sentence, not a length, and code adds the rest a section at a time. braid#38 trimmed it once; it grew back. **Fix** Review each part for who reads it and why. Then: - A title saying what changed, in plain words. - On top, a minute's read: what changed, what wasn't checked or needs a decision, how to try it. - The rest folded away, or left to the merge gate (braid#548). - No Braid terms. **Done when** That pull request, rewritten this way, reads in a minute and the owner prefers it. The next run's comes out the same way. Where to look: `build_summary` (`src/osf/engine/prompts.py`); `_title`, `_pr_body` (`src/osf/forgejo.py`); spec `pull-request-description`. *From the owner reading that pull request, 2026-11-20.*
Author
Owner

Shipped in #583 (merged as c9c5e63, live on production), and archived in #584.

  • A run's summary is now a title, one paragraph, what is not done and how to try it. summary-shape fails a summary out of that shape, naming what to change.
  • The pull request leads with the merge gate's checks, in its own words. It folds the code review (one line a note, its summary dropped), the tests and the run's figures. The run's link appears only on a private repository.
  • Run 204 rebuilt from its records: 258 words before the first fold, against 1,249 in all.
  • After the deploy, run 204's own summary step was captured from production and replayed on Free models with the new brief. It wrote a 59-character title, a 94-word paragraph, three Not done items and four steps using make test and make e2e, naming no lane, round or judge. Three replays of a simulated run's summary step passed the shape check too.
Shipped in #583 (merged as `c9c5e63`, live on production), and archived in #584. - A run's summary is now a title, one paragraph, what is not done and how to try it. `summary-shape` fails a summary out of that shape, naming what to change. - The pull request leads with the merge gate's checks, in its own words. It folds the code review (one line a note, its summary dropped), the tests and the run's figures. The run's link appears only on a private repository. - Run 204 rebuilt from its records: 258 words before the first fold, against 1,249 in all. - After the deploy, run 204's own summary step was captured from production and replayed on Free models with the new brief. It wrote a 59-character title, a 94-word paragraph, three Not done items and four steps using `make test` and `make e2e`, naming no lane, round or judge. Three replays of a simulated run's summary step passed the shape check too.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#570
No description provided.