git:20260619.ab60b18 to git:20260619.5580b59

---

name: clud-review

description: Pre-push code review gate. Inventories the changed files, groups them by language bucket, dispatches one review pass per non-empty bucket to a matching repo subagent or canned per-language template, and aggregates findings. Discovers .coderabbit.yaml, repo review skills/agents, CLAUDE.md/AGENTS.md guidance, and optionally runs the originating issue's focused test for RED -> GREEN validation. Read-only; called by /clud-fix or /clud-pr before `gh pr create`.

triggers:

- When the user says "/clud-review" or "/clud-review <commit-range>"

- When /clud-fix or /clud-pr is about to push a PR and the user wants a pre-flight review (called as a delegated step)

- When the user says "review this before pushing" with an active worktree

---

<!-- managed-by: clud -->

# /clud-review

Pre-push review gate that inventories the worktree's local diff,

classifies the changed files by language family, runs one focused

review per non-empty bucket using the project's actual rules, and

aggregates findings into a single Markdown table. Optionally runs

the originating issue's focused test for local RED -> GREEN validation.

`/clud-review` is the loop step the human reviewer would run if they

could be summoned at every push — same content they'd see, same rules

they'd apply, returned in seconds instead of days.

For code changes, the caller ([[clud-fix]] / [[clud-pr]]) preserves

RED -> GREEN: identify or add the focused failing test/repro first,

implement the scoped change, then rerun that focused signal until it

passes before broad gates. `/clud-review` ITSELF never edits code —

it surfaces findings; the caller's existing fix loop turns them GREEN.

Where the originating issue's focused test is discoverable, the

review explicitly runs it and reports pass/fail (RED -> GREEN

validation at the local level).

## Input

- **Bare** `/clud-review` — review `git diff origin/main...HEAD` from

the current working directory. The intended invocation point: a

`/clud-fix` or `/clud-pr` agent runs this as the last step before

`gh pr create`.

- **`/clud-review <commit-range>`** — review the specified range

(e.g. `HEAD~3..HEAD`).

- **`/clud-review --issue <N>`** — explicit issue number for the

issue-test discovery step below; otherwise inferred from branch /

commit messages.

## Hard Rules

1. **Pre-push only.** `/clud-review` reads the local diff; it does NOT

open the PR, post comments to GitHub, or modify any source. The

caller decides whether to act on findings.

2. **Use the repo's rules, not generic ones.** If the repo has a

`.coderabbit.yaml`, use its settings to bound and prioritize the

check. If the repo has review skills or subagents, dispatch to them.

If the repo has `CLAUDE.md` / `AGENTS.md`, include the relevant

sections. Generic feedback only fires as a *fallback* and is

labeled as such.

3. **Empty config = no-rules verdict.** If no review config or

per-language template applies to any bucket, emit

`clud-review: no-rules` and exit 0. Do not invent feedback.

4. **Read-only.** No file edits, no commits, no pushes.

5. **Structured findings.** Output is a Markdown table (Severity,

Bucket, File, Line, Finding, Suggested fix) plus a one-line

`clud-review: <status>` summary.

## Discovery — what to scan, where

### CodeRabbit config

Look at the repo root for, in priority order:

1. `.coderabbit.yaml` (canonical name per CodeRabbit docs)

2. `.coderabbit.yml`

The schema lives at https://coderabbit.ai/integrations/schema.v2.json

(noted for reference; do not fetch). Use these fields to shape the

review per bucket:

- `language` — language-specific rules per file extension; merge into

the matching bucket prompt.

- `reviews.path_filters` — files to include / exclude; apply BEFORE

bucketing so excluded paths never reach a review pass.

- `reviews.path_instructions` — per-glob review instructions; merge

into the prompt of whichever bucket the glob matches.

- `reviews.tools` — static-analysis tools the user expects; mention

them in the prompt so the agent can lean on their conventions.

- `chat.*` — irrelevant to a local review; ignore.

### Repo-level review skills

Scan:

- `.claude/skills/*/SKILL.md`

- `.codex/skills/*/SKILL.md`

- `skills/*/SKILL.md` (when the project keeps skills at the repo root)

Read each frontmatter. Include the skill when `name` or `description`

matches `/review|code\s*review/i`. Include the full `SKILL.md`

content in the matching bucket's prompt — when the skill is

language-scoped (e.g. its description mentions `rust` or `frontend`),

attach it only to that bucket; otherwise attach it to every bucket.

### Repo-level review subagents

Scan:

- `.claude/agents/*.md`

Read each frontmatter `description`. Include the subagent when it

matches `/review|code\s*review/i`. Subagents are *executed* (via the

Agent tool) when a bucket matches them — see "Per-bucket agent

selection" below.

### Guidance files

Scan:

- `CLAUDE.md` at the repo root

- `AGENTS.md` at the repo root (if present)

- Per-directory `CLAUDE.md` for directories that have changes in the

diff under review.

Extract sections matching `/code\s*(review|quality|standards?)/i` or

that read as rule-bullets (`must` / `should` / `never`). Attach to the

prompt of every bucket whose files live under the matching directory.

### Explicit skip rules

DO NOT scan:

- `~/.claude/` or `~/.codex/` — those are the agent's own user-level

configuration, not project rules.

- `~/.claude/rules/` — same reason (`code-review.md`, `security.md`,

`git-workflow.md` typically live there but encode the human user's

preferences, not the repo's).

- Third-party submodules.

- `target/`, `node_modules/`, `dist/`, or any other build artifact.

## File classification and per-language review dispatch

`/clud-review` does NOT generate one giant cross-language prompt. It

first inventories the changed files via

`git diff --name-status <base>...HEAD` (fallback:

`git status --porcelain` when no base is given), groups them by

language family, and runs one review pass per non-empty bucket.

### Bucket table

| Bucket | File extensions / names | Rationale |

|---|---|---|

| `rust` | `.rs`, `Cargo.toml`, `Cargo.lock` | Rust source + crate manifests |

| `cpp` | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.h++` | C++ source/header |

| `c` | `.c`, `.h` (when no `.cpp`/`.hpp` sibling) | Pure C — header `.h` alone defaults here; if a same-stem `.cpp` is in the diff, both go to `cpp` |

| `python` | `.py`, `pyproject.toml`, `setup.py`, `requirements*.txt` | Python source + packaging |

| `frontend` | `.html`, `.htm`, `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.less`, `.vue`, `.svelte`, `package.json`, `tsconfig*.json` | Browser/Node UI stack — reviewed together because changes typically cross files |

| `go` | `.go`, `go.mod`, `go.sum` | Go source + modules |

| `shell` | `.sh`, `.bash`, `.zsh`, `.ps1`, `.fish` | Shell scripts |

| `ci` | files under `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/` | CI/CD configuration |

| `config` | `.yaml`, `.yml`, `.toml`, `.json`, `.ini`, `.env*` (when NOT already claimed above) | Pure config that didn't claim a language |

| `docs` | `.md`, `.rst`, `.txt`, `.adoc` | Documentation and changelogs |

| `other` | everything else | Unclassified — reviewed with a generic prompt and a "best effort" disclaimer |

Bucket precedence is top-to-bottom: a file matches the **first** bucket

whose rule fires. So `Cargo.toml` is `rust` (not `config`), and

`.github/workflows/foo.yml` is `ci` (not `config`).

### Per-bucket agent selection

For each non-empty bucket, in priority order:

1. **Repo subagent match.** Scan `.claude/agents/*.md`. Match any

agent whose frontmatter `description` mentions the bucket name or

its primary language tooling (e.g. `rust` / `cargo` / `clippy` →

rust bucket; `frontend` / `react` / `tsx` / `css` → frontend

bucket; `cpp` / `c++` / `cmake` → cpp bucket). If a match exists,

dispatch the bucket's review to that subagent via the Agent tool

with the assembled bucket prompt.

2. **Repo skill match.** Otherwise, look for review skills whose

frontmatter narrows them to that language. Inline their

`SKILL.md` into the bucket's prompt as additional rules and use the

general agent.

3. **Canned per-language template.** If neither exists, use the canned

template for that bucket — a short language-specific review prompt

so the fallback isn't generic-shaped feedback. The canned templates

live in this skill's prose; representative examples:

- **rust**: idiomatic borrow semantics; `Result` over panics;

no `unwrap()` / `expect()` in non-test code; clippy `pedantic`

guidance; `unsafe` blocks must be justified with a `// SAFETY:`

comment.

- **cpp**: RAII; no raw `new` / `delete`; smart pointer ownership;

`const`-correctness; no implicit narrowing conversions.

- **python**: type hints; explicit exception handling; no

mutable default arguments; `pathlib` over string paths.

- **frontend**: accessibility (semantic HTML, ARIA); strict null

checks in TS; effect dependency arrays in React hooks; CSS

specificity; no inline event handlers in HTML.

- **shell**: `set -euo pipefail`; quoted variable expansions;

shellcheck-style rules.

- **ci**: pinned action versions; least-privilege tokens; secret

handling; matrix completeness.

- **config**: schema validity; no committed secrets; comment

intent on non-obvious values.

- **docs**: link integrity; example correctness; clear voice.

- **c**, **go**, **other**: brief generic guidance.

### Per-bucket prompt structure

Each bucket's assembled prompt is:

```text

You are reviewing local changes to <bucket-name> files before they

get pushed as a PR.

## Files in this bucket

<list of <bucket>-bucket file paths>

## Diff (filtered to bucket files)

git diff <base>...HEAD -- <bucket-paths>

## Repo-level rules (applicable to this bucket)

- From .coderabbit.yaml `language.<bucket>` or

`reviews.path_instructions` matching <bucket-paths>

- From any matched repo subagent (.claude/agents/<name>.md)

- From any matched review skill (.claude/skills/<name>/SKILL.md)

- From CLAUDE.md sections referencing <bucket-name> rules

- From the canned per-language template (only when none of the above

matched)

## Output format

Markdown table:

| Severity | File | Line | Finding | Suggested fix |

Severity ∈ {CRITICAL, HIGH, MEDIUM, LOW}.

```

### Aggregation across buckets

After all bucket reviews return, `/clud-review` aggregates them into a

single Markdown findings table with a `Bucket` column and a verdict

footer that breaks counts down per-bucket:

```text

clud-review: findings (3 CRITICAL [rust:2, frontend:1], 2 HIGH [rust:1, ci:1])

```

Empty buckets contribute nothing. If every bucket returns clean, the

verdict is `clud-review: clean`. If no bucket had any applicable rules

(no `.coderabbit.yaml`, no matched skills/agents, no relevant

`CLAUDE.md` sections, no canned template fired because the bucket was

`other`), the verdict is `clud-review: no-rules`.

### Bucket skip rules

- Empty bucket → skip entirely (no prompt, no agent call).

- `docs` bucket → only review if the docs change touches public

user-facing surfaces (e.g. `README.md`, `docs/`, `CHANGELOG.md`).

Skip per-directory `README.md` updates that mirror code-side

changes; those are documentation hygiene, not review-worthy.

- `config` bucket with only formatting changes (whitespace, comment

edits) → skip with a `clud-review: skipped config formatting` note.

## Issue-test discovery and execution

If `/clud-review` was invoked from `/clud-fix` or `/clud-pr` (or from a

worktree whose branch name encodes an issue number), it additionally

tries to find a focused test that **covers the originating issue** and

run it. Intent: RED -> GREEN validation at the local level — before

pushing, prove the issue-specific test passes.

### Discovering the issue number

In priority order, take the first hit:

1. **Caller-supplied** — `/clud-review --issue <N>` from the parent

skill's delegated call.

2. **Branch name** — if the current branch matches `feat/...-pr<N>` or

`fix/issue-<N>-*` or similar, extract `<N>`.

3. **Commit message** — scan `git log <base>..HEAD` for `Closes #<N>`,

`Fixes #<N>`, `Resolves #<N>`, or a `#<N>` in the first commit

subject.

4. **Diff content** — scan added test files for a literal `#<N>` in a

comment or docstring near a test definition.

If no issue number resolves, skip this section; review the diff

without an issue-test step.

### Finding tests that cover the issue

Once `<N>` is known, search across the standard test paths for tests

that reference it:

- **Rust**: `grep -rn "issue.*<N>\|#<N>" crates/*/tests/ crates/*/src/`

matching `#[test]` items.

- **Python**: `grep -rn "issue.*<N>\|#<N>" tests/` matching

`def test_*`.

- **JS/TS**: `grep -rn "issue.*<N>\|#<N>" __tests__/ test/ spec/`

matching `it(` / `test(` / `describe(`.

Rank candidates: tests added in the current diff > tests with the

issue number in their name > tests with the issue number in their

docstring or comment > tests in files the diff touched.

If multiple candidates rank equal, run all of them. If none match, log

`clud-review: no issue-specific test found for #<N>` and skip.

### Running the test

Use the project's standard test runner, inferred from the file

extension and the repo's CI script (`ci/test*.sh`, `bash test`,

`scripts/test`, etc.):

- Rust: `soldr cargo test -p <crate> --lib <test-name>` or

`--test <file>`.

- Python: `pytest tests/ -k <test-name>`.

- JS/TS: `npm test -- -t <test-name>` or `pnpm test -t <test-name>`.

Run with output capture. Two outcomes:

- **Test passes**: include `clud-review: issue-test #<N> passed

(<test-name>)` in the summary; review verdict is unaffected by this

alone (test pass is necessary but not sufficient for a clean review).

- **Test fails**: this is a CRITICAL finding. The diff failed to make

the issue test green. Surface the failure output as the finding body;

the verdict becomes `clud-review: findings (1 CRITICAL, ...)`.

### Don't run anything else

`/clud-review` does NOT run the full test suite — that's `bash test`'s

job. It runs *one* focused test (or a small set) that targets the

issue, then stops. Full-suite runs belong in the parent skill's

existing lint/test step.

## Invocation modes

### Bare `/clud-review`

Reviews `git diff origin/main...HEAD` from the current working

directory. The intended use: a `/clud-fix` or `/clud-pr` agent

invokes this as the last step before `gh pr create`. If findings are

non-empty (CRITICAL or HIGH), the caller should fix them and

re-review before pushing.

### `/clud-review <commit-range>`

Reviews the specified range (e.g. `HEAD~3..HEAD`). Useful for

reviewing a specific subset of work without pushing.

### Delegated from `/clud-fix` or `/clud-pr`

The two parent skills already have a "lint and test" step before push.

`/clud-review` slots in between "tests pass" and `gh pr create`:

```text

6. Lint and test.

6a. /clud-review (NEW STEP). If findings non-empty, address them,

re-lint, re-test, re-review. Loop until clean or until 3 review

cycles complete, then either push (clean) or surface the findings

and stop (not clean after 3 cycles).

7. Clean tree gate.

```

Wiring `/clud-review` into `/clud-fix` and `/clud-pr` is OUT OF SCOPE

for this skill's introduction — that's a follow-up PR. The SKILL.md

documents the delegated mode for forward compatibility.

## Generated prompt structure

The skill assembles **one prompt per non-empty bucket** (see "File

classification and per-language review dispatch" above). The

single-prompt shape described in "Per-bucket prompt structure" is the

full template; the aggregation step described in "Aggregation across

buckets" combines results into the user-visible output.

## Failure Modes To Avoid

- **Single cross-language prompt.** Don't lump rust + frontend + ci

into one review; the rules are too different and the agent's

attention fragments. Bucket first, then review.

- **Generic fallback masquerading as project rules.** When no repo

config matches, the canned per-language template fires — but the

output should clearly indicate it was a fallback so the user knows

to add `.coderabbit.yaml` or a review skill if they want richer

feedback.

- **Reviewing build artifacts.** `target/`, `node_modules/`, `dist/`,

build outputs from generated code (e.g. prost-generated `.rs` files)

should be excluded. Honor `.gitignore` and `.coderabbit.yaml` path

filters.

- **Blocking the push on advisory findings.** Only CRITICAL and HIGH

findings should block; MEDIUM and LOW are advisory. The caller's

fix loop decides whether to address them now or in a follow-up.

- **Mutating the repo.** `/clud-review` is read-only. No `git commit`,

no `git add`, no edits. Even fixing typos in CLAUDE.md is out of

scope.

- **Calling external services.** No network calls. No CodeRabbit

remote API, no `curl` of the schema URL. The local rules are the

source of truth.

- **Issue-test discovery false positives.** A grep for `#<N>` can

match unrelated test names or comments. Require the match to be

near a `#[test]` / `def test_` / `it(` definition, not just anywhere

in the file.

## When Not To Use This

- The user wants a post-PR / post-merge review of someone else's work

— that's [[clud-pr]] PR triage mode (look for CodeRabbit findings on

the existing PR) plus the user's own judgment.

- The user wants to file new issues from CodeRabbit findings on an

already-merged PR — that's [[clud-issue-triage]].

- The user wants the FULL test suite run — that's `bash test` or the

parent skill's lint/test step, not the focused issue-test runner here.

- The repo has no review configuration of any kind AND the user does

not want generic feedback — `/clud-review` will emit

`clud-review: no-rules` and exit; respect that as the answer.