From ea33fd635cf2c2980cfb6b639af9b76b4d247b19 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 18 Nov 2026 20:35:24 -0800 Subject: [PATCH 1/6] agents(review-code): fix mechanical nits directly and trim code snippets Posting inline review comments with verbatim re-wrapped code or trivial style fixes adds review churn on PRs where maintainer push access is available, while bare container types and unguarded `_fail` callbacks miss type and control-flow bugs in Starlark reviews. Classify mechanical formatting, docstring, `struct` comment, guard splitting, constant ordering, and `_fail` short-circuit findings for direct fix-and-push in `review-code`, omit replacement snippets when prose suffices, and document parameterized container types and `_fail` `None` guards in Starlark rules. --- .agents/rules/starlark.md | 7 +- .agents/skills/review-code/SKILL.md | 65 ++++++++++++++----- .../review-comment-readability-prompt.md | 23 +++++-- .../review-code/review-report-format.md | 24 ++++--- .../review-code/review-starlark-prompt.md | 9 ++- 5 files changed, 94 insertions(+), 34 deletions(-) diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index e9bbfe061c..97e657ed24 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -142,6 +142,10 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" above `provider()` declarations that do not end in `Info` (e.g. `*Fileset`). * **`config_setting` Naming**: Prefix `config_setting` names with `is_` (e.g. `is_linux_x86_64`), so that `select()` keys read as conditions. +* **Injectable `_fail = fail` Callbacks**: When a Starlark function accepts an + injectable `_fail = fail` callback for testing, immediately `return None` + after every `_fail(...)` call and guard `if result == None: return None` in + callers so non-aborting test callbacks do not execute invalid state. * **Explicit Required Parameters**: Declare required parameters explicitly instead of passing them through `**kwargs`. Document `Args:` and `Returns:`. * **Docstring Formatting Invariants**: Use triple-quoted strings for multi-line @@ -150,7 +154,8 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" arguments, link to shared symbols (`{obj}`) or guides (`{ref}`) instead of repeating rules, and put extended examples in `docs/`. * When returning a `struct(...)` of fields, add a comment above each field - describing its value. + describing its value and parameterized container element types (e.g., + `dict[str, list[str]]`, never bare `list` or `dict`). * **Workaround Comments**: Comment non-obvious workarounds with the intent, why the direct approach fails, and why the workaround works. * **No Bazel Copyright Headers**: Do not add Bazel copyright headers to new or diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 30fa6cafab..f067de38e2 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -126,11 +126,14 @@ file from `.agents/skills/review-code/`: 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 - (``, 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 + - Focus: Polishes `Problem`, `Proposed Fix`, `Draft Comment`, and + `Draft Reply` text for rendered readability—enforcing the mechanical + `Draft Comment` structure (``, + bounded `Suggested fix:`, and optional `Where:` when multiple locations + are affected), cutting dense "wall of text" paragraphs down to 1–2 short, + direct sentences, omitting verbatim code snippets when a concise prose + instruction suffices (formatting, per-field `struct(...)` comments, and + splitting compound boolean or inline ternary expressions), 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) @@ -169,11 +172,10 @@ file from `.agents/skills/review-code/`: ## Open Issues ### . [] — [:](file:///...) + * Action: * Problem: <1-2 sentences stating what is wrong and why.> - * Proposed Fix: - ``` - - ``` + * Proposed Fix: * Draft Comment (in user's voice): ```markdown @@ -196,6 +198,31 @@ file from `.agents/skills/review-code/`: ## Passing Domains ```` +- Omit verbatim code snippets from `Proposed Fix` and `Draft Comment` when a + concise prose instruction suffices: + - Formatting and line wrapping: state what formatting rule to apply (e.g., + wrap lines and `doc` strings to 80 columns) instead of pasting re-wrapped + code. + - Per-field `struct(...)` comments: state to document each field with a + comment instead of pasting a commented `struct(...)` block. + - Compound boolean or inline ternary expressions: describe how to split them + into explicit `if` statements instead of pasting a replacement block. +- When push access to the PR branch is available (`maintainerCanModify` is true + or the branch is in `rules_python`), set `Action: Fix directly and push to PR` + on mechanical, behavior-preserving findings rather than leaving nit review + comments for the author: + - Formatting and 80-column line wrapping (`*.bzl`, `doc` strings, `.md`). + - Trailing backslashes (`\`) on opening triple-quotes (`"""`) in multi-line + docstrings. + - `{ref}` roles when linking to narrative docs from `.bzl` docstrings. + - Per-field comments on returned `struct(...)` definitions. + - Splitting compound boolean guards and inline `or`/ternary expressions into + explicit `if` statements. + - `Args:` and `Returns:` sections on Starlark helper function docstrings. + - Defining module-level constants (including test constants) before + functions. + - Short-circuiting with `return None` (and guarding `None` in callers) after + injectable `_fail(...)` calls. - Whenever an open issue in `code-review-results.md` is resolved (via local edit, a new commit, or reviewer decision), move it from `## Open Issues` to `## Resolved Issues` (never delete it) and record how it was resolved. @@ -213,18 +240,24 @@ file from `.agents/skills/review-code/`: - Once all sub-agents finish, finalize `code-review-results.md` and provide a concise summary with the overall verdict and a clickable markdown link to `code-review-results.md` in the response. -- If reviewing a PR belonging to another user and at least one net-new candidate - comment remains after the Anti-Noise Gate, prompt the user via a single +- If reviewing a PR belonging to another user and at least one net-new open + issue remains after the Anti-Noise Gate, prompt the user via a single multi-select (`is_multi_select: true`) `ask_question` question (including a clickable `[code-review-results.md](file:///...)` link in the `question` prompt text) with the following options: 1. Post non-draft comments 2. Post draft comments - 3. Review feedback further - 4. Also approve PR - 5. Also fix issues - 6. Also push fixes to PR -- When fixing and pushing open issues that also had non-draft review comments + 3. Fix trivial issues and push to PR + 4. Review feedback further + 5. Also approve PR + 6. Also fix all issues + 7. Also push fixes to PR +- When `Fix trivial issues and push to PR` is selected, implement all + `Fix directly and push to PR` issues locally, verify with `buildifier` and + relevant `bazel test --config=fast-tests` targets, commit, and push explicitly + to the PR head branch (`git push HEAD:`). Do not post review + comments for issues fixed and pushed directly. +- When fixing and pushing open issues that already had non-draft review comments posted, reply to each fixed review thread with the commit SHA (and disclosure line) without resolving the thread unless explicitly instructed. - If reviewing or re-reviewing a PR belonging to another user and the verdict is diff --git a/.agents/skills/review-code/review-comment-readability-prompt.md b/.agents/skills/review-code/review-comment-readability-prompt.md index 521aac7414..b128c49df9 100644 --- a/.agents/skills/review-code/review-comment-readability-prompt.md +++ b/.agents/skills/review-code/review-comment-readability-prompt.md @@ -1,7 +1,8 @@ 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. +polish the `Problem`, `Proposed Fix`, `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 @@ -60,10 +61,20 @@ in Markdown (`code-review-results.md`) and GitHub pull request comments. - 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: +5. Omit Redundant Code Blocks, Keep Concrete Diagnostic Wording: + - Omit verbatim code snippets from `Proposed Fix` and `Draft Comment` when a + concise prose instruction suffices: + - Formatting and line wrapping: state what formatting rule to apply (e.g., + wrap lines and `doc` strings to 80 columns) instead of pasting re-wrapped + code. + - Missing per-field `struct(...)` comments: state to document each field + with a comment instead of pasting a commented `struct(...)` block. + - Compound boolean or inline ternary expressions: describe how to split + them into explicit `if` statements instead of pasting a replacement + block. - 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 + finding suggests specific wording for an error/failure message or a + non-trivial code change, `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 diff --git a/.agents/skills/review-code/review-report-format.md b/.agents/skills/review-code/review-report-format.md index 3d0d9c4d67..bdad4203f3 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md @@ -13,7 +13,12 @@ For each issue found, provide: - Problem: 1-2 sentences stating what is wrong and why (or, for `HUMAN-SIGN-OFF`, quoting the author's justification and evaluating whether it holds up). -- Proposed Fix: Concrete code snippet, diff, or replacement text. +- Proposed Fix: Concise prose fix instruction when a short description suffices, + or a concrete code snippet/diff for non-trivial changes. Omit verbatim code + snippets for formatting and line wrapping (state what formatting rule to + apply), missing per-field `struct(...)` comments (state to document each field + with a comment), and splitting compound boolean or inline ternary expressions + into explicit `if` statements. - 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): @@ -27,10 +32,13 @@ For each issue found, provide: ``` Keep `` 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. + lists, or `"conversely..."` chains). Omit verbatim code blocks from + `Suggested fix:` when prose suffices (formatting/line wrapping, per-field + `struct(...)` comments, and splitting compound boolean or inline ternary + expressions); when suggesting specific error/failure message wording or a + non-trivial code change, 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. diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md index 47450dc82d..b32d6678e3 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md @@ -35,11 +35,14 @@ in `git diff` against the project's Starlark coding rules and conventions: processable by `buildifier` and `buildozer`. 13. Check macro and rule hygiene: forward unused wrapper arguments via `**kwargs`, silence unused variables with `_ = a, b # @unused`, require - comments above each field when returning a `struct(...)` of fields, prefer - analysis-time validation over loading-time checks, prefer + comments above each field (with parameterized `list[...]` / `dict[...]` + element types, never bare `list` or `dict`) when returning a `struct(...)` + of fields, prefer analysis-time validation over loading-time checks, prefer `ctx.actions.write` over subprocesses for small static strings, use `$(execpath ...)` / `$(execpaths ...)` instead of `$(location)` / - `$(locations)`, and check public `.bzl` symbol removals/renames for breaking + `$(locations)`, verify functions with injectable `_fail = fail` callbacks + `return None` immediately after `_fail(...)` and callers guard against + `None`, and check public `.bzl` symbol removals/renames for breaking users. 14. Guardrails: Starlark is not Python (`== None` is correct, mutable defaults are frozen, no Python stdlib). Ignore `buildifier` formatting output and From b7019d74fb2e34ab28a429adb39645a35da83269 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 18 Nov 2026 20:52:33 -0800 Subject: [PATCH 2/6] agents(review-code): prefix trivial fix option with "Also" Clarify that fixing and pushing trivial issues composes with comment and approval actions in the multi-select review prompt. --- .agents/skills/review-code/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index f067de38e2..4304598bba 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -247,12 +247,12 @@ file from `.agents/skills/review-code/`: prompt text) with the following options: 1. Post non-draft comments 2. Post draft comments - 3. Fix trivial issues and push to PR + 3. Also fix trivial issues and push to PR 4. Review feedback further 5. Also approve PR 6. Also fix all issues 7. Also push fixes to PR -- When `Fix trivial issues and push to PR` is selected, implement all +- When `Also fix trivial issues and push to PR` is selected, implement all `Fix directly and push to PR` issues locally, verify with `buildifier` and relevant `bazel test --config=fast-tests` targets, commit, and push explicitly to the PR head branch (`git push HEAD:`). Do not post review From 9ee7148d17b610aff23d0b940afba0d504f99c31 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 18 Nov 2026 20:54:43 -0800 Subject: [PATCH 3/6] agents(review-code): summarize pushed trivial fixes in a PR comment Keep the PR author informed of pushed mechanical cleanups in a single summary comment without cluttering the diff with individual nit threads. --- .agents/skills/review-code/SKILL.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 4304598bba..def17f7def 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -254,9 +254,10 @@ file from `.agents/skills/review-code/`: 7. Also push fixes to PR - When `Also fix trivial issues and push to PR` is selected, implement all `Fix directly and push to PR` issues locally, verify with `buildifier` and - relevant `bazel test --config=fast-tests` targets, commit, and push explicitly - to the PR head branch (`git push HEAD:`). Do not post review - comments for issues fixed and pushed directly. + relevant `bazel test --config=fast-tests` targets, commit, push explicitly to + the PR head branch (`git push HEAD:`), and post a PR comment + summarizing the trivial issues fixed instead of posting individual inline + review comments for them. - When fixing and pushing open issues that already had non-draft review comments posted, reply to each fixed review thread with the commit SHA (and disclosure line) without resolving the thread unless explicitly instructed. From 748dc9e620a0a3d910da510ccd8383bcdc88ba3c Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 18 Nov 2026 20:57:53 -0800 Subject: [PATCH 4/6] agents(review-code): drop repeated parenthetical in report format Avoid repeating the prose-sufficient examples already listed under `Proposed Fix` in `review-report-format.md`. --- .../skills/review-code/review-report-format.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/.agents/skills/review-code/review-report-format.md b/.agents/skills/review-code/review-report-format.md index bdad4203f3..561ae05dde 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md @@ -33,12 +33,10 @@ For each issue found, provide: Keep `` to 1–2 short, direct sentences (no multi-clause "wall of text" paragraphs, parenthetical `e.g.` scenario lists, or `"conversely..."` chains). Omit verbatim code blocks from - `Suggested fix:` when prose suffices (formatting/line wrapping, per-field - `struct(...)` comments, and splitting compound boolean or inline ternary - expressions); when suggesting specific error/failure message wording or a - non-trivial code change, 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. + `Suggested fix:` when prose suffices; when suggesting specific error/failure + message wording or a non-trivial code change, 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. From 1fed97084516126a78f7e350691279c64c34cafc Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 18 Nov 2026 20:59:59 -0800 Subject: [PATCH 5/6] agents(review-code): split run-on checklists into bulleted lists Break long inline comma-separated enumerations in `review-starlark-prompt.md` and `SKILL.md` into bulleted lists and codify the rule in `agent-config.md` so prompts stay easy to scan and diff. --- .agents/rules/agent-config.md | 2 ++ .agents/skills/review-code/SKILL.md | 23 +++++++++---------- .../review-code/review-starlark-prompt.md | 23 ++++++++++--------- 3 files changed, 25 insertions(+), 23 deletions(-) diff --git a/.agents/rules/agent-config.md b/.agents/rules/agent-config.md index 3f15edfb44..470afe167d 100644 --- a/.agents/rules/agent-config.md +++ b/.agents/rules/agent-config.md @@ -9,4 +9,6 @@ globs: ".agents/**/*.md,AGENTS.md,CLAUDE.md,GEMINI.md" * Write in concise Strunk & White prose: omit needless words, use active voice, and state imperatives directly. * Do not use mannered prose, filler phrases, or verbose explanations. +* Format multi-item enumerations as bulleted lists rather than long run-on + comma-separated sentences so rules remain easy to read and review in diffs. * Wrap lines at 80 columns. diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index def17f7def..5b499f1981 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -127,18 +127,17 @@ file from `.agents/skills/review-code/`: - Prompt file: `.agents/skills/review-code/review-comment-readability-prompt.md` - Focus: Polishes `Problem`, `Proposed Fix`, `Draft Comment`, and - `Draft Reply` text for rendered readability—enforcing the mechanical - `Draft Comment` structure (``, - bounded `Suggested fix:`, and optional `Where:` when multiple locations - are affected), cutting dense "wall of text" paragraphs down to 1–2 short, - direct sentences, omitting verbatim code snippets when a concise prose - instruction suffices (formatting, per-field `struct(...)` comments, and - splitting compound boolean or inline ternary expressions), 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. + `Draft Reply` text for rendered readability: + - Enforce the mechanical `Draft Comment` structure (``, bounded `Suggested fix:`, and optional `Where:` + when multiple locations are affected). + - Cut dense "wall of text" paragraphs down to 1–2 short, direct + sentences. + - Omit verbatim code snippets when a concise prose instruction suffices. + - Include concrete suggested error/message wording in `Draft Comment` + (not left only in `Proposed Fix`). + - Remove excessive inline backticks across identifier lists (such as + `UPPER_SNAKE_CASE` constants) and strip outer backtick wrappers. ### Action Instructions - Immediately create a user-facing review artifact named diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md index b32d6678e3..471a0c18a0 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md @@ -33,17 +33,18 @@ in `git diff` against the project's Starlark coding rules and conventions: flag top-level target-instantiation ternaries (`rule_a(...) if cond else rule_b(...)`) that belong in a `.bzl` helper macro so `BUILD` files remain processable by `buildifier` and `buildozer`. -13. Check macro and rule hygiene: forward unused wrapper arguments via - `**kwargs`, silence unused variables with `_ = a, b # @unused`, require - comments above each field (with parameterized `list[...]` / `dict[...]` - element types, never bare `list` or `dict`) when returning a `struct(...)` - of fields, prefer analysis-time validation over loading-time checks, prefer - `ctx.actions.write` over subprocesses for small static strings, use - `$(execpath ...)` / `$(execpaths ...)` instead of `$(location)` / - `$(locations)`, verify functions with injectable `_fail = fail` callbacks - `return None` immediately after `_fail(...)` and callers guard against - `None`, and check public `.bzl` symbol removals/renames for breaking - users. +13. Check macro and rule hygiene: + - Forward unused wrapper arguments via `**kwargs`. + - Silence unused variables with `_ = a, b # @unused`. + - Comment each field when returning a `struct(...)`, using parameterized + `list[...]` / `dict[...]` element types (never bare `list` or `dict`). + - Prefer analysis-time validation over loading-time checks. + - Prefer `ctx.actions.write` over subprocesses for small static strings. + - Use `$(execpath ...)` / `$(execpaths ...)` instead of `$(location)` / + `$(locations)`. + - Return `None` immediately after injectable `_fail(...)` calls + (`_fail = fail`) and guard against `None` in callers. + - Check public `.bzl` symbol removals or renames for breaking users. 14. Guardrails: Starlark is not Python (`== None` is correct, mutable defaults are frozen, no Python stdlib). Ignore `buildifier` formatting output and unowned wrapper macro docstrings. From e2d8193c994800eeba70343fac2d7ce2a7d73150 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 18 Nov 2026 21:29:32 -0800 Subject: [PATCH 6/6] agents(review-code): address pre-PR review findings in agent configs Align `_fail` short-circuit guidance with `buildifier` `return-value` rules across void, boolean, and value-returning Starlark functions, require fail-closed ref validation and `--` when pushing to external PR branches, allow reviewer summary comments for pushed fixes in `AGENTS.md` and `pr.md`, and split remaining multi-item instructions into bulleted lists. --- .agents/rules/pr.md | 4 ++- .agents/rules/starlark.md | 8 +++-- .agents/skills/review-code/SKILL.md | 21 ++++++----- .../review-code/review-report-format.md | 35 ++++++++++--------- .../review-code/review-starlark-prompt.md | 5 +-- AGENTS.md | 5 +-- 6 files changed, 46 insertions(+), 32 deletions(-) diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index c3815f7322..acb6b46f3c 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md @@ -51,7 +51,9 @@ Before drafting any pull request description, strictly adhere to the rules in existing PR (such as a Dependabot PR); instead, disclose AI authorship only on comments you actually post (see below). Never post comments for every CI run or narrate build IDs, commit SHAs, line counts, or trivial diff details - (e.g., "comment-only"); comment `PTAL` only when ready for re-review. + on your own PR (e.g., "comment-only"); comment `PTAL` only when ready for + re-review, or post a single summary comment when pushing direct fixes while + reviewing another author's PR. * High-level overview only: state *why* the change is made and *how* at a conceptual level. * **Issue References**: Reference issues in PR descriptions (e.g., `Work towards diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index 97e657ed24..eddf0bc57f 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -143,9 +143,11 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" * **`config_setting` Naming**: Prefix `config_setting` names with `is_` (e.g. `is_linux_x86_64`), so that `select()` keys read as conditions. * **Injectable `_fail = fail` Callbacks**: When a Starlark function accepts an - injectable `_fail = fail` callback for testing, immediately `return None` - after every `_fail(...)` call and guard `if result == None: return None` in - callers so non-aborting test callbacks do not execute invalid state. + injectable `_fail = fail` callback for testing, return immediately after + every `_fail(...)` call using the function's return convention (bare `return` + in void functions, `return False` in boolean validators, or `return None` in + value-returning functions) and guard error returns in callers so non-aborting + test callbacks do not execute invalid state. * **Explicit Required Parameters**: Declare required parameters explicitly instead of passing them through `**kwargs`. Document `Args:` and `Returns:`. * **Docstring Formatting Invariants**: Use triple-quoted strings for multi-line diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 5b499f1981..a3011eb39f 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -220,8 +220,9 @@ file from `.agents/skills/review-code/`: - `Args:` and `Returns:` sections on Starlark helper function docstrings. - Defining module-level constants (including test constants) before functions. - - Short-circuiting with `return None` (and guarding `None` in callers) after - injectable `_fail(...)` calls. + - Short-circuiting immediately after injectable `_fail(...)` calls (using + bare `return`, `return False`, or `return None` to match the function's + return convention) and guarding error returns in callers. - Whenever an open issue in `code-review-results.md` is resolved (via local edit, a new commit, or reviewer decision), move it from `## Open Issues` to `## Resolved Issues` (never delete it) and record how it was resolved. @@ -251,12 +252,16 @@ file from `.agents/skills/review-code/`: 5. Also approve PR 6. Also fix all issues 7. Also push fixes to PR -- When `Also fix trivial issues and push to PR` is selected, implement all - `Fix directly and push to PR` issues locally, verify with `buildifier` and - relevant `bazel test --config=fast-tests` targets, commit, push explicitly to - the PR head branch (`git push HEAD:`), and post a PR comment - summarizing the trivial issues fixed instead of posting individual inline - review comments for them. +- When `Also fix trivial issues and push to PR` is selected: + - Implement all `Fix directly and push to PR` issues locally. + - Verify with `buildifier` and relevant `bazel test --config=fast-tests` + targets. + - Commit the fixes without amending existing PR commits. + - Validate `` and `` fail-closed (rejecting `..`, leading + `-`, `:`, control characters, and shell metacharacters) and push via + `git push -- "HEAD:refs/heads/"`. + - Post a single PR comment summarizing the trivial issues fixed instead of + posting individual inline review comments for them. - When fixing and pushing open issues that already had non-draft review comments posted, reply to each fixed review thread with the commit SHA (and disclosure line) without resolving the thread unless explicitly instructed. diff --git a/.agents/skills/review-code/review-report-format.md b/.agents/skills/review-code/review-report-format.md index 561ae05dde..88246e0be1 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md @@ -13,12 +13,14 @@ For each issue found, provide: - Problem: 1-2 sentences stating what is wrong and why (or, for `HUMAN-SIGN-OFF`, quoting the author's justification and evaluating whether it holds up). -- Proposed Fix: Concise prose fix instruction when a short description suffices, - or a concrete code snippet/diff for non-trivial changes. Omit verbatim code - snippets for formatting and line wrapping (state what formatting rule to - apply), missing per-field `struct(...)` comments (state to document each field - with a comment), and splitting compound boolean or inline ternary expressions - into explicit `if` statements. +- Proposed Fix: Concise prose fix instruction when a short description + suffices, or a concrete code snippet/diff for non-trivial changes. Omit + verbatim code snippets for: + - Formatting and line wrapping (state what formatting rule to apply). + - Missing per-field `struct(...)` comments (state to document each field with + a comment). + - Splitting compound boolean or inline ternary expressions into explicit `if` + statements. - 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): @@ -30,13 +32,14 @@ For each issue found, provide: Where: ``` - Keep `` to 1–2 short, direct sentences - (no multi-clause "wall of text" paragraphs, parenthetical `e.g.` scenario - lists, or `"conversely..."` chains). Omit verbatim code blocks from - `Suggested fix:` when prose suffices; when suggesting specific error/failure - message wording or a non-trivial code change, 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. + Format `Draft Comment` as follows: + - Keep `` to 1–2 short, direct sentences + (no multi-clause "wall of text" paragraphs, parenthetical `e.g.` scenario + lists, or `"conversely..."` chains). + - Omit verbatim code blocks from `Suggested fix:` when prose suffices. + - Include concrete suggested text in `Suggested fix:` inside `Draft Comment` + (not only in `Proposed Fix`) when proposing specific error/failure message + wording or a non-trivial code change. + - Avoid wrapping lists of visually distinct identifiers (such as + `UPPER_SNAKE_CASE` constants) in individual backticks, and never wrap the + entire comment in outer backticks. diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md index 471a0c18a0..8acf47d485 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md @@ -42,8 +42,9 @@ in `git diff` against the project's Starlark coding rules and conventions: - Prefer `ctx.actions.write` over subprocesses for small static strings. - Use `$(execpath ...)` / `$(execpaths ...)` instead of `$(location)` / `$(locations)`. - - Return `None` immediately after injectable `_fail(...)` calls - (`_fail = fail`) and guard against `None` in callers. + - Return immediately after injectable `_fail(...)` calls (`_fail = fail`) + using the function's return convention (bare `return`, `return False`, or + `return None`) and guard error returns in callers. - Check public `.bzl` symbol removals or renames for breaking users. 14. Guardrails: Starlark is not Python (`== None` is correct, mutable defaults are frozen, no Python stdlib). Ignore `buildifier` formatting output and diff --git a/AGENTS.md b/AGENTS.md index f33bc53d4b..cae8f71d8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,8 +72,9 @@ execution logs, or check checklists in the PR description. trivial diff details (e.g., stating a push is "comment-only"). GitHub already displays commits and check statuses. * **Comment only when actionable:** Only post a PR comment to answer a - reviewer's question, ask a clarifying question, or briefly indicate the PR - is ready for re-review (e.g., `PTAL`) once CI is passing. + reviewer's question, ask a clarifying question, summarize direct fixes pushed + while reviewing another author's PR, or briefly indicate the PR is ready for + re-review (e.g., `PTAL`) once CI is passing. ### Python pytest conventions