review

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 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:

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.
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 — 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 rule id (e.g. vgv/missing-null-check) the user can act on as a class.
• On the default branch with no diff, scope is ambiguous. The skill asks; do not default to reviewing the whole project without confirmation.
• Agent failures are non-fatal. Always report which agents failed so the user knows the review is incomplete.
• Auto-fix only touches files within the original scope. If a fix needs changes outside scope, flag it instead of silently expanding scope.

Important

• One consolidated report per run. Per-agent raw reports live in docs/code-review/<slug>/raw/ for drill-down and are linked from the consolidated file.
• Reports are untracked working files. Commit or delete them when no longer needed.
• This skill is advisory. It presents findings and lets the user decide what to act on.
• When in doubt about a finding, read its linked raw report for full detail before deciding.