From c63bc6a4344d764d425c1d55091952d643917ac0 Mon Sep 17 00:00:00 2001 From: Cristian Greco Date: Wed, 1 Jul 2026 09:18:40 +0100 Subject: [PATCH] Document review-comment style and approval gate in AGENTS.md Add guidance to the PR Review section so review feedback is consistent and low-noise: - Get explicit user approval before posting any review feedback to GitHub, even when asked to review a PR (clarifies PR Process step 6). - Keep each comment terse: problem, minimal context, what to do instead. - Anchor comments inline; keep the summary body to must-address points. - Verify against the rest of the repo before claiming a convention violation; scope to concrete inconsistencies. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 39f90ee50..57b46895f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,6 +117,21 @@ When reviewing a PR (your own or someone else's), the review is not only about t - Check that labels (change type and semver impact) are present and correct. - Check that docs were updated alongside any public API change. +Before posting any review feedback to GitHub, share the proposed comments with the user and get +explicit approval (this is the review-specific case of PR Process step 6). Present the full set of +comments for a quick sanity check first; do not post directly, even when explicitly asked to +review a PR. + +When writing review comments, keep each one terse and actionable for the PR author: + +- State the problem, at most a sentence of context if it helps, and what to do instead. Skip + restated background, meta-commentary, and severity labels the author does not need. +- Anchor comments inline on the relevant line rather than dumping everything in the review body. + Keep the summary body to the few must-address points plus any high-level design note. +- Only claim something violates convention after checking the rest of the repo. Prefer scoping a + comment to a concrete inconsistency (for example "the other blocks in this file do X") over a + broad assertion that may be wrong. + ## Labels ### Change type