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/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 e9bbfe061c..eddf0bc57f 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -142,6 +142,12 @@ 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, 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 @@ -150,7 +156,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..a3011eb39f 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -126,16 +126,18 @@ 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 - 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. + - Focus: Polishes `Problem`, `Proposed Fix`, `Draft Comment`, and + `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 @@ -169,11 +171,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 +197,32 @@ 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 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. @@ -213,18 +240,29 @@ 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. 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 `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. - 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..88246e0be1 100644 --- a/.agents/skills/review-code/review-report-format.md +++ b/.agents/skills/review-code/review-report-format.md @@ -13,7 +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: 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). + - 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): @@ -25,12 +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). 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. + 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 47450dc82d..8acf47d485 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md @@ -33,14 +33,19 @@ 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 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 - 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 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 unowned wrapper macro docstrings. 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