/code-review

name: code-review
description: "Review or improve code — one skill, four modes: bug/security review (default), performance, clean-code audit, slop cleanup. Pass mode:review|perf|clean|cleanup or infer. Don't use for writing features or generating tests (use test-coverage)."
license: MIT
effort: high
metadata:
  version: 2.2.2
  author: "Luong NGUYEN <luongnv89@gmail.com>"
  architecture: "router (4 modes, each a self-contained workflow in references/)"

Code Review

One skill for reviewing and improving code quality. Pick a **mode** by intent (or pass an explicit `mode:` parameter); each mode is a full, self-contained workflow in `references/`. Load only the mode you need — this protects the agent's context budget.

Modes

| Mode | Use when the user wants to... | Reads / writes | Output | Workflow | |---|---|---|---|---| | **review** (default) | find bugs, security holes, quality issues in a diff/PR | read-only | prioritized findings report | `references/review-mode.md` | | **perf** | make code faster — bottlenecks, leaks, algorithmic waste | read-only | performance findings report | `references/perf-mode.md` | | **clean** | audit readability/standards vs the bbv Clean Code cheat sheet | read-only | `CLEAN_CODE_AUDIT.md` | `references/clean-mode.md` | | **cleanup** | actually refactor out AI slop, dead code, duplication, cruft | **WRITES CODE** | modified source files | `references/cleanup-mode.md` |

Selecting the mode

1. **Explicit wins.** If the request carries `mode:review|perf|clean|cleanup` (or `--mode <name>`), use it. 2. **Otherwise infer** from the request. When one matched phrase sits inside a longer matched phrase, only the longer one counts, so "clean code review" is a **clean** phrase only, not also a **review** phrase. Phrases that do not overlap all count, whatever their length (step 3).

• "review", "find bugs", "security", "is this correct", "look for vulnerabilities" → **review**
• "slow", "faster", "optimize", "bottleneck", "memory leak", "performance" → **perf**
• "clean code audit" (or "clean-code audit"), "clean code review", "check this against clean code" → **clean**

(user-invoked only — a bare "readability" or "audit against standards" ask is ambiguous: use step 3)

• "remove slop", "clean up the codebase", "refactor out cruft / dead code / duplication" → **cleanup**

3. **No match, or phrases from more than one mode?** Ask which mode, naming the four options. For example, "review and optimize" matches **review** and **perf**, so ask. Use **review** without asking only when the request contains a review phrase and no other mode's phrase.

Safety: cleanup writes code — the other three do not

`review`, `perf`, and `clean` are **source-read-only**: they analyze and report without touching source files. Review and perf may write only the named report artifact their mode specifies (`CODE_REVIEW.md` for review; perf returns its report in the response). During review/perf analysis, they must not otherwise mutate the index, refs, stash, branch, worktree, or remote state. `clean` retains its own report-writing and sync contract. `cleanup` **modifies files**. Therefore:

• **Never enter `cleanup` by weak inference.** Run it only when the user explicitly asks to

refactor / clean up the codebase (or passes `mode:cleanup`). A plain "review my code" must never rewrite files — stay in a read-only mode.

• Review and perf analysis record `git rev-parse HEAD`, `git status`, and local tracking

observations without claiming remote freshness. They do not fetch, stash, pull, rebase, checkout/switch, create or delete branches/worktrees, or apply source fixes. A separately approved mutation workflow owns its own freshness and stash-first sync contract.

• **Confirm before the first write** in `cleanup`, and follow that mode's own gating.

Repo Sync Before Edits (mandatory)

Applies to `clean` (writes `CLEAN_CODE_AUDIT.md`) and `cleanup` (writes source) only. `review` and `perf` never sync (see the Safety section). Before the first write in either mode:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"

• If the working tree is dirty in `clean`, stash first, sync, then pop the stash.
• If the working tree is dirty in `cleanup`, stop and ask the user to commit or stash first.
• If `origin` is missing, or the pull or stash pop conflicts, stop and ask the user. Do not write any file.
• If the target is not a git repo, `clean` skips the sync and notes that in its report.

The full step, with recovery commands, is in `references/clean-mode.md` and `references/cleanup-mode.md`.

Run the mode's workflow

Read the selected mode's reference file and execute its steps exactly. Supporting files each mode uses (already colocated under this skill):

• **review** → `references/review-mode.md` — agents `agents/reviewer.md`, `agents/file-reviewer.md`, `agents/report-assembler.md`; refs `references/subagent-architecture.md`, `references/code-smells.md`
• **perf** → `references/perf-mode.md` — ref `references/language-checks.md`
• **clean** → `references/clean-mode.md` — refs `references/clean-code-checklist.md`, `references/tdd-checklist.md`, `references/html-report-guide.md`, `references/report-template.html`
• **cleanup** → `references/cleanup-mode.md` — the 8 cleaner agents in `agents/` (`deduplicator.md`, `type-consolidator.md`, `unused-code-killer.md`, `circular-dep-untangler.md`, `weak-type-strengthener.md`, `defensive-programming-remover.md`, `legacy-code-remover.md`, `slop-comment-cleaner.md`)

Environment Check

If the Agent tool is available, modes that use subagents (**review**, **cleanup**) spawn them per their workflow — fresh-context validation and parallel work. If it is unavailable (e.g., Claude.ai), execute each mode's phases inline (less rigorous, but functional).

Chaining modes

Modes compose: a common flow is **clean** (audit → `CLEAN_CODE_AUDIT.md`) then