From 9c7687cc914cd8eddee7ba25cb980ad1a6bc0fdc Mon Sep 17 00:00:00 2001 From: Will Pfleger Date: Fri, 25 Sep 2026 14:41:56 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20docs:=20add=20pre-PR=20checklist?= =?UTF-8?q?=20and=20review=20guidance=20to=20AGENTS.md=20(#7897)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Before opening a PR" checklist and "Reviewing" guidance to `AGENTS.md`, and makes the Review-Proven Rules the shared reviewer checklist. PRs stay in draft until an agent review has run, an agent has exercised the change on the affected surface, and a human has tested it. The review-completed passphrase goes in the description only once that checklist holds for the current change, and comes out if later edits change behavior. Docs-only changes use the light path: content, link, and diff checks plus human confirmation. Reviews read `VISION.md` and the surface's `VISION_*.md` first, check the change against the Review-Proven Rules, recommend blocking only for concrete correctness, security, or contract defects with a realistic failure, label everything else optional, and put all findings in the first pass. Agents comment and never use Request Changes; humans decide which findings must be fixed. Related: [block/buzz-app#268](https://github.com/block/buzz-app/pull/268) --------- Signed-off-by: Duncan Signed-off-by: Will Pfleger Co-authored-by: Duncan --- AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 58309c0865..3c9d578bb9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,48 @@ and runtime evidence answer different questions. --- +## Before opening a PR + +Open work in progress as a draft PR. Mark it ready for review only when this +checklist holds for the current change. Scale it to what changed: +documentation-only changes need content, link, and diff checks plus human +confirmation, not app runs. + +1. **Agent review ran** under [Reviewing](#reviewing), and its recommended + blockers were fixed or explicitly declined by the human author. Optional + suggestions do not gate readiness. +2. **An agent exercised the changed behavior.** Client changes: the affected flow + in the app, using the native app or a device when the behavior needs it + (browser or headless Playwright counts only for what it can exercise). Relay + changes: a local relay, exercising the changed events or endpoints. CLI or + tooling changes: the affected command or workflow. The human may skip this + step, for example for a small change or while iterating. +3. **A human then tested it themselves**: in the app, against the local relay + (through the app or `curl`), or by running the changed command. Agent testing + does not substitute. Agents give the human exact steps and what working looks + like, then wait for explicit confirmation. Never mark this step done yourself. +4. **Add `buzz-review-completed` to the PR description** once steps 1–3 hold. It + attests the checklist, and automated reviewers may skip review because of it. + If later edits change behavior, remove it and return the PR to draft until the + affected steps are redone. + +## Reviewing + +- Before reviewing, read [VISION.md](VISION.md), the `VISION_*.md` docs for the affected surface, and the PR's stated goal and linked + issue. Review the change against what it is trying to do. +- Check the change against the [Review-Proven Rules](#review-proven-rules): the defects reviewers here find most often. +- Judge minimalism, elegance, and correctness, aiming for 9/10 on each. A score + below 9 names the concrete defect and the fix. +- Recommend blocking only for concrete correctness, security, or agreed-contract + defects with a realistic failure scenario: state the defect, how it fails, and + the fix. Label everything else (nits, wording, speculative hardening, + out-of-scope improvements) as optional. +- Put all findings in the first review. Later reviews check prior blockers and + defects the fixes introduced; reopen other areas only on new evidence of a + material defect. +- Agents post reviews as comments, never Request Changes. Humans decide which + findings must be fixed. + ## Ecosystem Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay, desktop, mobile, and CLI. The others handle internal builds and deployment: @@ -165,8 +207,8 @@ the same clusters and measured how often authors actually fix each class once flagged: test-seam binding and unbounded-resource findings were fixed **100%** of the time, swallowed-error findings **90%**, stale-state races **70%** — these are not style opinions, they are defects authors agree -with on sight. Apply the rules **before writing code**; each cites the -PRs where reviewers litigated it. +with on sight. Authors apply them **before writing code**, and reviewers check +against them; each cites the PRs where reviewers litigated it. 1. **Every caught failure must leave a durable retry record or propagate.** Never catch-log-and-return-success (opt-out revocation permanently