/review

name: review
user-invocable: true
description: Runs quality review agents on demand — reviews code against VGV standards for architecture, tests, and simplicity, then writes one consolidated, numbered report.
when_to_use: Use when user says "review this code", "review my code", "code review", "review", "check this code", or "review before merging".
argument-hint: "[path/to/files/or/directories (optional)]"
allowed-tools: Bash(*/scripts/detect-review-scope.sh) Bash(gh *) Bash(glab *)
effort: high
compatibility: Designed for Claude Code (or similar products with agent support)

Review code on demand

Run quality review agents. Review manually written code, assess existing codebases, or check a branch before merging. Output is **one consolidated report** with stable, numbered findings the user can act on by id.

Review Scope

<review_scope>$ARGUMENTS</review_scope>

Step 1 — Detect Scope

Parse the review scope above for optional file paths or directories.

**If paths are provided:**

1. Validate each path exists (split on whitespace, check each token). 2. Use provided paths as review scope. Derive the scope slug deterministically from the first path: drop any file extension, then replace `/` with `-` (`lib/auth/` → `lib-auth`, `lib/auth/token.dart` → `lib-auth-token`). Same paths always give the same slug. 3. Announce scope to the user and proceed to Step 2.

**If no paths provided:**

Run the scope detection script:

${CLAUDE_SKILL_DIR}/scripts/detect-review-scope.sh

• **If `SCOPE=branch`**: use the listed files as scope. The scope slug is the current

branch name with `/` replaced by `-`. Announce scope summary (changed-file count, areas affected) and proceed to Step 2.

• **If `SCOPE=default`**: tell the user "You're on `<CURRENT_BRANCH>`. No branch diff

available." Use **AskUserQuestion**: "What would you like to review?" with options:

• **Specify files or directories**: accept paths; derive the slug from the first path as above.
• **Review entire project**: no scope constraint; slug `project`.

Step 2 — Run Reviews

Run `pwd` and let `<PWD>` be the result — subagents may change directories, making relative paths unreliable. Each run gets its own directory `<PWD>/docs/code-review/<slug>/`, so raw per-agent reports go in `<PWD>/docs/code-review/<slug>/raw/` (absolute) and one run never clobbers another branch's kept report.

Run the **default review agents** below **in parallel**. Projects may add agents in their `CLAUDE.md` (include them alongside the defaults) or replace the default set entirely.

Each agent prompt must include:

1. **The scope constraint** — changed-file list, specific paths, or no constraint. 2. **The [review agent instructions](references/review-agent-instructions.md)** with `<RAW_DIR>` set to `<PWD>/docs/code-review/<slug>/raw` and `<name>` set to the agent's report name below (a bare stem — the agent writes `<RAW_DIR>/<name>.md`). Substitute `<PWD>` and `<slug>` with their resolved values — do not pass a relative path.

Default agents and their report names (`<name>`):

| Agent | Report name | |-------|-------------| | **@vgv-review-agent** | `vgv-review` | | **@architecture-review-agent** | `architecture-review` | | **@test-quality-review-agent** | `test-quality-review` | | **@code-simplicity-review-agent** | `code-simplicity-review` |

**If an agent fails:** note it, continue with the successful agents, and record the failure in the report header and chat summary so the user knows the review is incomplete. Offer to retry.

Step 3 — Consolidate & Present

Follow the [review consolidation procedure](references/review-consolidation.md):

1. Collect every agent's structured findings, deduplicate, order deterministically, and assign stable `FINDING-NN` ids. 2. Write **one** consolidated file to `<PWD>/docs/code-review/<slug>/review.md` using the [report template](references/review-report-template.md). 3. Print the aligned chat summary: lead with the report path and severity counts, then reprint the Critical and Important rows verbatim (same ids, order, titles) and collapse Suggestions to a count.

**If no findings:** write the short all-clear report and tell the user the code looks good.

Step 4 — Act

This skill is advisory — take no action until the user picks one. Use **AskUserQuestion** to present post-review options (the ids and rules follow the consolidation procedure's "Acting on findings" section):

• **Fix critical issues**: address every Critical finding by id, then run the project's

linter and test runner. One attempt per fix; if validation fails, report what failed and move on. Only modify files within the original review scope.

• **Fix critical + important**: same, plus Important findings.
• **Fix specific findings**: accept ids from the user (e.g. "FINDING-01, FINDING-04"), or a

rule id to act on a whole class (e.g. "fix every `tests/missing-test-file`").

• **File findings on the PR as comments**: follow [file findings on the PR](references/file-findings-on-pr.md)

— a two-step flow that first asks which findings to include, then how to deliver them (inline comments, one summary comment, or print the drafts for the user to post manually).

• **Keep report and exit**: the report stays at `docs/code-review/<slug>/` for manual review.

**After fixing (if chosen):** re-run linter + test runner (no agent re-run), then present a brief summary of which findings (by id) were fixed.

Gotchas

• Each run writes to its own `docs/code-review/<slug>/` directory (report + `raw/`). Re-running

the same scope overwrites only that slug's directory; a different branch or path uses a different slug, so a report you keep is never clobbered by a later run of another scope.

• Because ids come from a deterministic sort (severity → file → line → rule), re-running on

unchanged code produces the same ids — `FINDING-03` keeps pointing at the same issue. Each finding also carries a stable r