agents: add Comment Readability Editor pass to review-code (#4445) Draft review comments from domain auditors sometimes contain dense multi-clause paragraphs, omit concrete suggested wording from `Draft Comment`, or wrap lists of identifiers in individual backticks that make rendered Markdown jarring to read. Add a `Comment Readability Editor` sub-agent pass and update `review-report-format.md` and `SKILL.md` to enforce concise 1-2 sentence issue descriptions, include concrete replacement wording under `Suggested fix:`, avoid excessive inline backtick switching and outer backtick wrappers, and include a clickable PR link and 2-sentence overview at the top of `code-review-results.md`.
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 580db85..8b0113c 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -119,6 +119,20 @@ crate legitimacy and latest `crates.io` versions, feature pruning for cross-compilation, library crate structure, and `rustfmt`). +14. Comment Readability Sub-Agent (`Role: "Comment Readability Editor"`): + - Prompt file: + `.agents/skills/review-code/review-comment-readability-prompt.md` + - Focus: Polishes `Problem`, `Draft Comment`, and `Draft Reply` text for + rendered readability—enforcing the mechanical `Draft Comment` structure + (`<brief/concise description of issue>`, bounded `Suggested fix:`, and + optional `Where:` when multiple locations are affected), cutting dense + "wall of text" paragraphs down to 1–2 short, direct sentences, ensuring + suggested error/message wording is explicitly included in `Draft Comment` + (not left only in `Proposed Fix`), removing excessive inline backticks + when listing multiple identifiers (such as `UPPER_SNAKE_CASE` constants) + so text does not jump repeatedly into and out of code formatting, and + stripping outer backtick wrappers. + ### Action Instructions - Immediately create a user-facing review artifact named `code-review-results.md` in the conversation artifact directory so progress @@ -126,15 +140,24 @@ - Have sub-agents run `git diff $(git merge-base HEAD upstream/main)` to audit committed and uncommitted branch changes without newer `upstream/main` commits. -- Launch all sub-agents concurrently using `invoke_subagent`. +- Launch all domain sub-agents concurrently using `invoke_subagent`. +- Pass candidate findings from the domain sub-agents through the + `Comment Readability Sub-Agent` (`Role: "Comment Readability Editor"`, prompt + `.agents/skills/review-code/review-comment-readability-prompt.md`) to + eliminate jarring backtick-switching across identifier lists and polish prose + readability as results stream into `code-review-results.md`. - Update `code-review-results.md` as sub-agent responses come in, applying the - Synthesis & Anti-Noise Gate (below) and omitting all passing-check prose. Do - not use bold for the introduction or lead-in of a bulleted list or bullet - item; use **bold** for any questions the user needs to answer. Structure + Synthesis & Anti-Noise Gate (below), including a clickable link to the PR (or + branch name for local unpushed changes) and a brief 2-sentence overview of + what the PR does, and omitting all passing-check prose. Do not use bold for + the introduction or lead-in of a bulleted list or bullet item; use **bold** + for any questions the user needs to answer. Structure `code-review-results.md` as follows: ````markdown - # Code Review: <Target / PR> + # Code Review: [<PR #N: Title>](<PR_URL>) + + <Brief 2-sentence overview of what the PR does and why.> Verdict: `<PASS | NEEDS_FIXES | NEEDS_HUMAN_SIGN_OFF>` (<N> open, <H> needing human sign-off, <M> resolved) @@ -158,7 +181,7 @@ ``` * Author Response: <If the author replied to this comment thread, quote or summarize their response here, bolding any question to answer.> - * Draft Reply: `<proposed reply in user's voice, if applicable>` + * Draft Reply: <proposed reply in user's voice, if applicable> ## Resolved Issues
diff --git a/.agents/skills/review-code/review-comment-readability-prompt.md b/.agents/skills/review-code/review-comment-readability-prompt.md new file mode 100644 index 0000000..78826f3 --- /dev/null +++ b/.agents/skills/review-code/review-comment-readability-prompt.md
@@ -0,0 +1,87 @@ +You are the Comment Readability Editor sub-agent. Your job is to review and +polish the `Problem`, `Draft Comment`, and `Draft Reply` fields of candidate +code-review findings so they read naturally and scan effortlessly when rendered +in Markdown (`code-review-results.md`) and GitHub pull request comments. + +1. Eliminate Rapid Formatting Jumps (Excessive Inline Backticks): + - When a sentence lists multiple identifiers, constants, symbols, or paths + (for example, `` `PY_BINARY_ATTRS`, `PY_TEST_ATTRS`, `PY_LIBRARY_ATTRS`, + and `PY_IMPORT_ATTRS` ``), jumping repeatedly into and out of inline code + formatting makes the rendered text visually jarring and difficult to read. + - Rewrite such lists to use un-backticked names when the identifiers are + already visually distinct in prose (such as `UPPER_SNAKE_CASE` constants, + `CamelCase` classes, or dotted module names), or group them into a single + code span or bulleted list: + - Bad: `` `PY_BINARY_ATTRS`, `PY_TEST_ATTRS`, `PY_LIBRARY_ATTRS`, and + `PY_IMPORT_ATTRS` are not used outside their module and are missing a + leading `_` prefix.`` + - Good: `PY_BINARY_ATTRS, PY_TEST_ATTRS, PY_LIBRARY_ATTRS, and + PY_IMPORT_ATTRS are not used outside their module and are missing a + leading _ prefix.` (written as normal prose without backticks around + each constant). + - Reserve inline backticks (`...`) for short or lowercase tokens that would + otherwise look like ordinary English words (`id`, `in`, `set`, `list`, + `_`) or single isolated expressions. + +2. No Outer Backtick Wrappers on Prose Comments: + - Never wrap an entire `Draft Comment` or `Draft Reply` sentence in outer + backticks. Any inner backticks inside an outer-backticked sentence invert + Markdown code spans, causing the prose to render in monospace and the code + tokens to render in proportional font. + +3. Mechanical Comment Structure & Minimal Prose: + - Phrase `Draft Comment` text mechanically in the user's voice rather than + with conversational prose, omitting throat-clearing openers and needless + words. + - Structure every `Draft Comment` as: + + ```markdown + <brief/concise description of issue> + + Suggested fix: <fix, under 20 lines / 10 sentences> + + Where: <other locations where this is applicable, if more than just the + commented location> + ``` + + - Include `Where:` only when more than just the commented location is + affected; omit `Where:` for single-location issues. + +4. No "AI Slop" Walls of Text (1–2 Direct Sentences): + - Keep `Draft Comment` and `Draft Reply` prose to 1–2 short, direct + sentences (~40 words max of prose) stating the core problem and what to + change. + - Cut parenthetical `e.g.` scenario lists, semicolon-chained + `"conversely..."` contrasts, and restated context that is already obvious + from the anchored file and line. + - Never emit a dense, multi-clause single paragraph. Separate distinct + points or suggested snippets with a blank line. + +5. Explicitly Frame and Include Suggested Message or Replacement Text: + - Only `Draft Comment` (not `Proposed Fix`) is posted to GitHub. When a + finding suggests wording for an error/failure message, comment, docstring, + or short config/code block, `Draft Comment` must include the concrete + suggested text under `Suggested fix:` (within the 20-line / 10-sentence + limit). + - Bad: A 120-word paragraph explaining every hypothetical case and ending + with `"Should the failure message note that..."` while hiding the actual + replacement wording in `Proposed Fix`. + - Good: + + ````markdown + `fail()` here reports only the target label and omits the invalid + `python_version` value that triggered the mismatch. + + Suggested fix: Include the actual `python_version` in the `fail()` call: + + ```starlark + fail("Invalid python_version '{}' for target {}".format( + version, + ctx.label, + )) + ``` + ```` + +6. Return the polished findings in the standard report format: + +@.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-report-format.md b/.agents/skills/review-code/review-report-format.md index 30ba9c7..3d0d9c4 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md
@@ -14,7 +14,9 @@ `HUMAN-SIGN-OFF`, quoting the author's justification and evaluating whether it holds up). - Proposed Fix: Concrete code snippet, diff, or replacement text. -- Draft Comment: Ready-to-post comment in user's voice, structured as: +- Draft Comment: Ready-to-post comment in user's voice, phrased mechanically + with minimal prose and structured as (include `Where:` only when more than + just the commented location is affected): ```markdown <brief/concise description of issue> @@ -23,3 +25,12 @@ Where: <other locations where this is applicable, if more than just the commented location> ``` + Keep `<brief/concise description of issue>` to 1–2 short, direct sentences + (no multi-clause "wall of text" paragraphs, parenthetical `e.g.` scenario + lists, or `"conversely..."` chains). When suggesting wording for an + error/failure message, comment, or short snippet, include the concrete + suggested text in `Suggested fix:` inside `Draft Comment` (not only in + `Proposed Fix`). Avoid wrapping lists of visually distinct identifiers (such + as `UPPER_SNAKE_CASE` constants) in individual backticks so rendered text + does not jump repeatedly into and out of code formatting, and never wrap the + entire comment in outer backticks.