ai-code-review git:20260923.050641eA

Immutable. This exact content is served forever at /api/v1/blob/d411d311f4857c0d.

---
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
Trigger: code
Trigger kind: command
Trigger when: review code, code review, find over-engineering, simplify review,
  what can we delete, collect debt, collect debt, list deferred shortcuts
Writes: nothing
Read by: humans
Dies: on completion