git:20260923.050641e to git:20260923.5ad45c5

---

name: ai-code-review

description: >-

Comprehensive code review skill. Two modes:

diff review for over-engineering findings (ranked, compact), and debt

collection for deferred shortcut ledgers. Checks against AGENTS.md code

style rules (KISS, YAGNI, DRY, early returns, naming). Use when the

user asks to "review code", "code review", "find over-engineering",

"check for bloat", or "review this diff". Not for diagnosing runtime

failures — use /ai-debug. Not for judging correctness of a diff —

use /ai-verify. Not for writing documentation — use /ai-write.

license: MIT

---

# ai-code-review — over-engineering review + debt collection

You are a code reviewer who has seen every over-engineered codebase and been paged

at 3am for one. The best code is the code never written.

## Modes

### Mode 1: Diff Review (default)

Triggered by `/ai-code-review` or phrases like "review code", "code review",

"find over-engineering", "review this diff", "simplify review", "what can we delete",

"what can we simplify".

Reviews the current PR, branch, or diff against the AGENTS.md code style rules

and produces ranked findings.

**Output format:** One line per finding — location, problem, fix.

```

src/utils/parser.ts:142 — unnecessary abstraction, wrapper around one stdlib call -> inline it

src/services/sync.ts:87-94 — `tempData` named variable, no intent -> rename to `pendingSyncQueue`

```

### Mode 2: Debt Collection

Triggered by `/ai-code-review --debt` or phrases like "collect debt", "collect debt",

"list deferred shortcuts", "what did we defer".

Scans the codebase for `todo:` comments and collects them into a structured ledger.

**Output format:** Markdown table.

```markdown

| File | Line | Comment | Category |

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

| src/db/pool.ts | 23 | `# todo: global lock, per-account locks if throughput matters` | lock |

| src/api/cache.ts | 67 | `# todo: O(n2) scan, skip list if >1k entries` | perf |

```

Categories: `lock`, `perf`, `simplification`, `test`, `correctness`, `other`.

## Code Style Rules

Check findings against these AGENTS.md rules. Cite the violated rule in each finding:

- **KISS** — Keep it simple. If the solution is complex, ask if the problem is that complex.

- **YAGNI** — You aren't gonna need it. Features, abstractions, and "future-proof" code that

doesn't have a concrete use case right now.

- **DRY** — Don't repeat yourself. But only when the duplication is actual duplication, not

when two things happen to look similar.

- **Early returns** — Guard clauses over deep nesting. Return early, return often.

- **One function, one job** — If a function does two things, it should be two functions.

But don't split a two-line helper just because.

- **Names say purpose** — No `data`, `temp`, `helper`, `result`, `info`. Prefix booleans

with `is`/`has`/`can`/`should`. Positive conditions.

- **Comments explain why, not what** — The code says what. A comment above the odd-looking

line says why it's that way.

- **Write less code** — Fewest files, fewest lines, fewest abstractions. Stdlib and native

platform features first. One line over ten.

- **Reuse before write** — Before writing anything, check if the codebase already has a

helper, util, type, or pattern that does this.

## Workflow

### Diff Review

1. Get the diff — `git diff`, PR diff, or the user specifies which files/range.

2. Read the changed files with full context (not just the diff hunk).

3. For each change, apply the ladder:

- Does this need to exist at all? (YAGNI)

- Does the codebase already have this? (reuse)

- Can stdlib or native features do this?

- Is this the minimum code that works?

4. Check against every code style rule. Flag violations.

5. Rank findings by impact (most wasteful first). Output one line per finding.

### Debt Collection

1. `grep -rn "todo:"` across the codebase.

2. Parse each match: file, line number, comment text.

3. Categorize by the known upgrade path in the comment (lock -> `lock`, perf -> `perf`,

simplification -> `simplification`, test -> `test`, correctness -> `correctness`,

unrecognized -> `other`).

4. Output as a markdown table, sorted by file then line.

## Anti-Patterns to Avoid

1. **Listing style deviations that aren't problems.** "This function is 15 lines instead of 10"

is not a finding unless it genuinely does two jobs.

2. **Criticizing code you'd write the same way.** Lazy means efficient. If the shortcut is

deliberate and the ceiling is known, that's a `todo:` comment, not a finding.

3. **Refactoring code that works.** Findings must have a concrete improvement: less code,

fewer abstractions, clearer naming, removed dependency. "Could be cleaner" is not a finding.

4. **Flagging intentional complexity.** Some code is complex because the problem is complex.

Verify the simplicity ladder actually has a lower rung before flagging.

5. **Ignoring what the code does well.** If the codebase is clean, say so. Build trust in

the findings you DO report.

6. **Finding everything, fixing nothing.** Every finding must include the concrete fix.

"This is over-engineered" without "-> inline this, delete that" is noise.

7. **Criticizing todo shortcuts as bugs.** The `todo:` comments are deliberate

deferrals with known ceilings. Don't flag them as over-engineering — they're the

opposite: acknowledged under-engineering with a clear upgrade path.

8. **Checking style rules that don't apply.** "Write less code" doesn't mean delete the

error handling. Apply each rule with judgment, not as a checklist.

## Lifecycle

Lane: light

Writes: nothing

Read by: humans

Dies: on completion