/clean-code-review

← Back to index

Summary

Code done — get the deep read before it ships. Runs 132 checks across 7 groups (clarity, smells, SOLID, arch, tests, safety, DDD), spawns one agent per group in parallel, and synthesizes findings by severity. Works on local changes, staged files, git ranges, a pull/merge-request link, or explicit paths — no git required for file-path mode.

Scripted detections run first via collect.sh and are handed to the group agents as precomputed hits — agents confirm or dismiss each one rather than re-running detection. Vendor and generated files are excluded upfront. Per-check findings can be capped on very large diffs; the report notes it when that happens.

When to use

You've written the code and want a structured review before opening a PR — not a vibe check, a systematic pass across 132 named criteria. Use /clean-code-review when you want findings grouped, labeled by severity, and synthesized into a clear action list.

The skill declares no trigger phrases — invoke it directly with /clean-code-review.

Invocation

/clean-code-review [TARGET ...] [GROUP ...]

Targets (default: all local changes):

Groups (case-insensitive, omit to run all 7):

A token that matches a group name is always treated as a group, never as a file or ref — e.g. /clean-code-review tests selects the tests group, not a directory named tests.

Language gate: if no supported language file is detected in the target, the review aborts before spawning any agent: "No supported language files detected. Supported: TypeScript, JavaScript, C#, Python, Swift, Kotlin, Java, C++. Unanalysed: {contents of unanalysed.txt}."

Severity levels: Critical (blocks correctness, security, or safety) · Major (significant design flaw, missing requirement, or likely bug) · Moderate (suboptimal but workable) · Minor (style, naming, or nitpick)

Example 1 — Full review of local changes (illustrative example)

Input:

/clean-code-review

Output / Result:

## Clean Code Review

**5 findings · 0 Critical · 4 Major · 0 Moderate · 1 Minor** (post-deduplication)
**Target:** staged unstaged untracked
**Groups run:** clarity, smells, solid, arch, tests, safety, ddd · 132 checks declared
**Languages detected:** typescript

---

### `src/services/UserService.ts`

[solid-01] · Major · Single Responsibility Principle | src/services/UserService.ts:12 | Split UserService — separate auth, email, and billing into distinct classes

### `src/services/PaymentProcessor.ts`

[solid-05] · Major · Dependency Inversion Principle | src/services/PaymentProcessor.ts:34 | Replace direct dependency on PostgresClient with an interface — inject the implementation
[smells-04] · Major · Code Duplication | src/services/PaymentProcessor.ts:58 | Remove duplicate validation logic — reuse existing validateInput in src/utils/validation.ts

### `src/services/__tests__/PaymentProcessor.test.ts`

[tests-07] · Major · Test Edge Case Coverage | src/services/__tests__/PaymentProcessor.test.ts:20 | Add edge case test for chargeCard — cover null input

### `src/utils/format.ts`

[clarity-02] · Minor · Function/Method Naming | src/utils/format.ts:8 | Rename doStuff to formatCurrency — name does not express intent

Example 2 — Single group on a git range (illustrative example)

Input:

/clean-code-review main..HEAD safety

Output / Result:

## Clean Code Review

**2 findings · 1 Critical · 1 Major · 0 Moderate · 0 Minor** (post-deduplication)
**Target:** ref: main..HEAD
**Groups run:** safety · 32 checks declared
**Languages detected:** python

---

### `src/services/order_service.py`

[safety-01] · Critical · Resource Leak | src/services/order_service.py:23 | Wrap db_connection in a `with` block to guarantee cleanup

### `src/services/notification_service.py`

[safety-06] · Major · Blocking I/O in Async Context | src/services/notification_service.py:41 | Replace blocking requests.get inside async send_notification with an async HTTP client

Related tools