Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agents/rules/agent-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 3 additions & 1 deletion .agents/rules/pr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 8 additions & 1 deletion .agents/rules/starlark.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
80 changes: 59 additions & 21 deletions .agents/skills/review-code/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
(`<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.
- Focus: Polishes `Problem`, `Proposed Fix`, `Draft Comment`, and
`Draft Reply` text for rendered readability:
- Enforce the mechanical `Draft Comment` structure (`<brief/concise
description of issue>`, 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
Expand Down Expand Up @@ -169,11 +171,10 @@ file from `.agents/skills/review-code/`:
## Open Issues

### <ID>. [<SEVERITY>] <Short title> — [<file>:<line>](file:///...)
* Action: <Post comment | Fix directly and push to PR>
* Problem: <1-2 sentences stating what is wrong and why.>
* Proposed Fix:
```<lang>
<replacement snippet or diff>
```
* Proposed Fix: <concise prose fix instruction, or replacement snippet/diff
when non-trivial>
* Draft Comment (in user's voice):
```markdown
<brief/concise description of issue>
Expand All @@ -196,6 +197,32 @@ file from `.agents/skills/review-code/`:
## Passing Domains
<Comma-separated list of audited domains with 0 issues>
````
- 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.
Expand All @@ -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 `<remote>` and `<branch>` fail-closed (rejecting `..`, leading
`-`, `:`, control characters, and shell metacharacters) and push via
`git push -- <remote> "HEAD:refs/heads/<branch>"`.
- 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
Expand Down
23 changes: 17 additions & 6 deletions .agents/skills/review-code/review-comment-readability-prompt.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
29 changes: 19 additions & 10 deletions .agents/skills/review-code/review-report-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -25,12 +32,14 @@ For each issue found, provide:
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.
Format `Draft Comment` as follows:
- 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).
- 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.
21 changes: 13 additions & 8 deletions .agents/skills/review-code/review-starlark-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 3 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading