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.