.agents/skills/review-code/SKILL.md

---
name: review-code
description: High-level code review audit of local changes when preparing to
  send a PR for review
trigger: model_decision
---

When preparing to send a Pull Request for review, invoke **separate, concurrent
sub-agents** (`invoke_subagent`), where each sub-agent focuses exclusively on
its assigned checklist category.

**CRITICAL**: Do NOT use a single sub-agent to validate multiple or all
dimensions at once. Each sub-agent must be launched with its own distinct prompt
file from `.agents/skills/review-code/`:

### Audit Checklist & Sub-Agent Prompts

1. **Starlark / Bazel Sub-Agent** (`Role: "Starlark Code Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-starlark-prompt.md`
   - Focus: Audits Starlark / Bazel changes (`*.bzl`, `BUILD`, `*.bazel` files)
     in `git diff` against `.agents/rules/bzl.md` and Starlark rules in
     `AGENTS.md`.

2. **Python Code Sub-Agent** (`Role: "Python Code Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-python-prompt.md`
   - Focus: Audits Python source, test, and inline script changes in `git diff`
     against `.agents/rules/python.md` and Python and pytest conventions in
     `AGENTS.md`.

3. **Documentation Sub-Agent** (`Role: "Documentation Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-docs-prompt.md`
   - Focus: Audits documentation (`.md`) changes and docs build targets against
     `.agents/rules/docs.md` and `AGENTS.md`.

4. **Contribution Guidelines Sub-Agent** (`Role: "Contributing Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-contributing-prompt.md`
   - Focus: Audits changes, requirements updates, and version directives against
     `CONTRIBUTING.md`.

5. **Project Conventions Sub-Agent** (`Role: "Project Conventions Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-agents-prompt.md`
   - Focus: Audits overall workspace compliance against `AGENTS.md`.

6. **Pull Request Standards Sub-Agent** (`Role: "PR Standards Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-pr-standards-prompt.md`
   - Focus: Audits PR titles and descriptions against Conventional Commits
     formatting, PR update rules in `CONTRIBUTING.md`, and open questions or
     "TODO / Things we could do" items in the PR description (ensuring the
     `"do not merge"` label is applied when open questions exist).

7. **GitHub Workflows Sub-Agent** (`Role: "GitHub Workflows Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-workflows-prompt.md`
   - Focus: Audits workflow files (`.github/**`) and workflow tests against
     `.agents/rules/github_actions_workflows.md` (e.g. `chmod +x` executable
     permissions, shebangs, action and tool versions,
     `./.github/actions/setup-bazel` wrapper usage, fallback jobs, and shell,
     script, CLI flag, `$GITHUB_OUTPUT`, or workflow-command injection
     vulnerabilities).

8. **`rules_python` Usage Sub-Agent** (`Role: "rules_python Usage Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-rules-python-prompt.md`
   - Focus: Audits changes against `.agents/rules/rules_python.md` (e.g.,
     `pip.dep()` declarations in `MODULE.bazel` and `MINIMUM_BAZEL_VERSION`
     bounds).

9. **News Entry Sub-Agent** (`Role: "News Entry Auditor"`):
   - Prompt file:
     `.agents/skills/review-code/review-news-prompt.md`
   - Focus: Audits `news/<id>.<category>.md` files for presence, naming (no
     generic `0000` placeholders), brevity and skimmability, and formatting
     against `.agents/rules/news.md` and
     `.agents/skills/create-news/SKILL.md`.

10. Code Style & Architecture Sub-Agent
    (`Role: "Code Style & Architecture Auditor"`):
    - Prompt file:
      `.agents/skills/review-code/review-code-style-prompt.md`
    - Focus: Audits cross-language code style across all code files (`*.py`,
      `*.rs`, `*.sh`, `*.cc`, `*.h`, `*.go`, `*.bzl`, `*.bazel`): file
      definition order, guard clauses, fail-closed `else`, single input form,
      no unrequested knobs/aliases, no speculative validation or defensive
      `None` checks, no nested comprehensions, naming precision,
      simplification, `keep-sorted` markers, `LINT.IfChange` /
      `LINT.ThenChange` directives, and CLI safety annotations.

11. Shell Script Sub-Agent (`Role: "Shell Script Auditor"`):
    - Prompt file:
      `.agents/skills/review-code/review-shell-prompt.md`
    - Focus: Audits `*.sh`, git hooks, and inline shell scripts against
      `.agents/rules/shell.md` and `.agents/rules/code-style.md` (long flags
      and commented short flags, direct shebang invocation, GNU `getopt --name`,
      `(set -x; ...)`, `Modifies:` doc sections, no blind `|| true`, and no `$?`
      checks under `set -e`).

12. Justification & Exception Sub-Agent
    (`Role: "Justification & Exception Auditor"`):
    - Prompt file:
      `.agents/skills/review-code/review-justification-auditor-prompt.md`
    - Focus: Evaluates all stated or missing justifications for rule exceptions
      (such as `sys.path`/`ImportError` probing, lint/type/buildifier
      suppressions, custom timeouts/retries, or review replies claiming a rule
      does not apply), rejecting missing, circular, or inaccurate excuses as
      `SHOULD-FIX` and flagging plausible technical constraints as
      `HUMAN-SIGN-OFF`.

13. Rust Sub-Agent (`Role: "Rust Code Auditor"`):
    - Prompt file:
      `.agents/skills/review-code/review-rust-prompt.md`
    - Focus: Audits Rust code (`*.rs`, `crates/**`) and crate dependencies in
      `MODULE.bazel` / `Cargo.*` against `.agents/rules/rust.md` (standard
      ecosystem crates over custom subsystems such as regex or ZIP handling,
      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
  is visible right away.
- 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 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), 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: [<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)

  ## Open Issues

  ### <ID>. [<SEVERITY>] <Short title> — [<file>:<line>](file:///...)
  * Problem: <1-2 sentences stating what is wrong and why.>
  * Proposed Fix:
    ```<lang>
    <replacement snippet or diff>
    ```
  * Draft Comment (in user's voice):
    ```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>
    ```
  * 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>

  ## Resolved Issues

  * ~~<ID>. [<SEVERITY>] <Short title> ([<file>:<line>](file:///...))~~ —
    Resolved: <How it was fixed or resolved (e.g., fixed in commit N,
    updated in working copy, or dismissed per reviewer).>

  ## Passing Domains
  <Comma-separated list of audited domains with 0 issues>
  ````
- 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.
- If the PR author posts a question or reply requiring reviewer input on a
  comment thread, record their response (`* Author Response: ...`) and a
  proposed `* Draft Reply` under the corresponding issue in
  `code-review-results.md`, then prompt the user via `ask_question` (including a
  clickable `[code-review-results.md](file:///...#L<start>-L<end>)` link in the
  `question` prompt text).
- Never auto-resolve a rule exception solely because the author added a
  justification comment or reply. Whenever a justification is present or added,
  use the `Justification & Exception Auditor` to evaluate it, rejecting weak or
  inaccurate justifications as `SHOULD-FIX` and keeping plausible justifications
  open as `[HUMAN-SIGN-OFF]` until the user explicitly signs off.
- 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
  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
  posted, reply to each fixed review thread with the commit SHA (and disclosure
  line) and resolve the thread.
- If reviewing or re-reviewing a PR belonging to another user and the verdict is
  `PASS` (0 open issues and 0 net-new candidate comments) while the PR is not
  yet approved by the user, prompt the user via `ask_question` (including a
  clickable `[code-review-results.md](file:///...)` link in the `question`
  prompt text) to choose whether to:
  1. Approve PR
  2. Do nothing
  3. Re-review
- Immediately before posting comments (after `ask_question` returns), re-fetch
  the latest PR description, commits, and review comments (`gh pr view`), move
  any issues addressed in the interim to `## Resolved Issues` in
  `code-review-results.md`, and drop their candidate comments.
- When posting comments or replies to a PR, append an italicized disclosure line
  at the end of each comment:
  `*This is an agent-generated comment reviewed and approved by the user.*` if
  the user reviewed and approved posting the comment, or
  `*This is an automatically generated agent comment.*` if posted without user
  review.

### Synthesis & Anti-Noise Gate (Guardrails)

When aggregating sub-agent findings into `code-review-results.md` and before
posting comments, filter out noise:

1. Starlark is not Python: Do not leak Python complaints into Starlark (`.bzl`,
   `BUILD`, `*.bazel`). Starlark has no `is` operator (`== None` is correct),
   freezes default arguments (mutable defaults are safe), accepts `# @unused` or
   `# buildifier: disable=...` suppressions, and prefers explicit `len()`
   checks. Do not suggest Python stdlib functions.
2. Third-Party, Vendored, & Generated Code: Never nitpick style or structure in
   third-party imported, vendored, lockfile, or generated files (such as
   `*requirements*.txt`, `gazelle_python_manifest.yaml`, or patches). Only flag
   build breakages or license issues.
3. Formatter-Handled Output: Never ask to revert a formatter's output (such as
   `buildifier`, `ruff`, or `rustfmt` quote/comma/order changes, trailing
   newlines, or markdown hard-break backslashes).
4. `TODO` Syntax: Do not complain about `TODO(...)` formatting or demand a
   username or issue number. Drop `TODO` syntax nits entirely.
5. Rule Over-Application:
   - Only flag a redundant comment when it literally restates the code. Never
     remove a "why" rationale or Arrange/Act/Assert test headers.
   - Naming nits must be objective (redundant qualifier, misleading term, or
     cryptic abbreviation), not subjective taste.
   - Do not require docstrings on wrapper macros where the signature is
     forwarded via `**kwargs`, or enforce explicit types when duck-typing is the
     established pattern.
6. Verify Before Claiming: A finding that asserts a behavior must quote the
   exact line(s). If uncertain about external tool or API semantics, phrase it
   as a `QUESTION` ("Does X do Y here?") rather than a factual assertion.
7. No Persona Flourishes in Posted Comments: Review comments posted to GitHub
   must contain only technical review content and the trailing italicized
   agent-generated disclosure line. Never include conversational chat persona
   flourishes (song lyrics, jokes, sassy remarks) in posted review comments.
8. Follow-Up Etiquette: Do not block on explicit "postponed to a follow-up"
   notes or minor out-of-scope follow-ups.
9. No Speculative Defensive Checks: Do not invent hypothetical edge cases (such
   as "if list is empty, indexing raises"). Assume callers provide valid domain
   inputs unless there is concrete evidence otherwise.
10. Specific Test Requests: Do not demand tests vaguely ("please add tests");
    always specify the exact behavior, edge case, or branch that needs testing.
11. Consolidation (>= 15 Findings): If sub-agents produce 15 or more findings
    total, consolidate repeated nits into a single comment ("same here and N
    other places") or omit the lowest-priority formatting nits first without
    suppressing naming precision or simplification findings.
12. Deduplicate Against Existing Comments: Inspect existing PR review comments
    and suppress candidate comments that duplicate feedback already posted.
13. Preserve Documented Rule Findings: Keep every sub-agent finding backed by
    `.agents/rules/` or `AGENTS.md` in `## Open Issues`, regardless of `NIT`
    severity or legacy patterns in existing files.