SuperAPI AI Directory

code-review

Coding & development

View repository

Updated 11-14 17:50

About this skill

Code Review

Review code against the style guide in references/style-guide.md. Produce a structured, severity-tagged findings report that a human can skim in 30 seconds and an agent can act on directly.

What gets reviewed

Default scope, in order of preference:

  1. Explicit target — if the user names a file, PR, branch, or diff, review exactly that
  2. Current branch vs main — git diff main...HEAD when reviewing "my changes" / "this branch"
  3. Uncommitted changes — git diff HEAD + git diff --staged when reviewing "what I just wrote"
  4. Ask — only if genuinely ambiguous. Don't ping-pong.

Skim the diff first, then read surrounding context for any file with non-trivial changes. A review that misses the calling context misses half the bugs.

Output format

Always use this structure. Omit sections that are empty — don't pad with "no issues found".

# Code Review — <what was reviewed>

**Summary**: <1-2 sentences. What changed, overall shape of the feedback.>

## Blockers
<Bugs, security issues, broken contracts, data loss risks. Must fix before merge.>

- **<file>:<line>** — <what's wrong>. <why it matters>. <concrete fix>.

## Major
<Style-guide violations with real cost: hidden dependencies, swallowed errors, leaky boundaries, wrong abstraction.>

## Minor
<Naming, guard clauses, section ordering, missing types. Worth fixing, not urgent.>

## Nits
<Taste-level preferences. Author may ignore.>

## Praise
<1-3 specific things done well. Not filler — skip if there's nothing genuine.>

Each finding is one bullet, one issue, one fix. If you're writing a paragraph, split it.

What to look for

Work through these lenses. Not every lens applies to every review — skip ones that aren't relevant rather than manufacture findings.

1. Correctness (blocker-tier)

  • Off-by-one, null/undefined handling, race conditions, unawaited promises
  • Silent error swallowing — catch {}, discarded Result.error, ignored rejections
  • Mutations on shared/aliased state
  • Idempotency: will a retry duplicate work or corrupt state?
  • Boundary validation: is untrusted input validated before it enters the type system?

2. Style-guide adherence

Cross-reference references/style-guide.md. The high-value checks:

  • Naming: vague (data, result, temp), missing units (timeout vs timeoutMs), abbreviations (cfg, cust), booleans without prefix (valid vs isValid), nouns where verbs belong (email() vs sendEmail())
  • Guard clauses: nested conditionals that could be flattened, happy path buried >2 levels deep
  • Progressive disclosure: helpers above public API, types scattered instead of grouped, file that doesn't answer "what is this?" in first 10 lines
  • Explicit dependencies: globals, singletons, ambient imports; things a function uses that aren't in its signature
  • Error handling: throw where Result fits, any/unknown leaking, opaque messages ("Validation failed")
  • Single responsibility: functions doing two things, and in the name, >50 lines without a clear reason

3. Agentic / context hygiene

This is where most reviews miss things:

  • Leaky context boundaries: module imports from 4+ siblings to do one job
  • Token bloat: functions returning the kitchen sink when callers want a summary
  • Unstructured outputs: prose where a discriminated union or typed object belongs
  • Missing machine-parseable errors: error strings instead of { code, retryable }
  • Convention drift: new code that doesn't match established patterns in the same module

4. Minimalism

  • Premature abstraction (1-2 call sites, not 3+)
  • Speculative generality (options/flags nothing uses)
  • Dead code, unused exports, commented-out blocks
  • Comments that explain what instead of why (rename the thing instead)
  • Backwards-compat shims for code that isn't shipped yet

5. Testing

  • Missing tests on new behaviour; tests that assert implementation not behaviour
  • Tests coupled to internals (mocking private methods, asserting call counts)
  • One test doing five things
  • Golden-path-only: no failure case coverage

6. Security & side effects (blocker if present)

  • SQL/command/template injection, unescaped user input reaching a sink
  • Secrets in code, logs, or commit
  • Auth/authz checks missing or bypassable
  • Broad catch that hides security-relevant failures
  • Unintended network calls, file writes, or process spawns

7. Commit & PR hygiene (if reviewing a branch/PR)

  • Multiple unrelated concerns in one commit/PR
  • Commit messages that say what not why
  • Drive-by refactors mixed with the core change

Calibrating severity

Err toward fewer, sharper findings over exhaustive lists. A 40-item review gets ignored; a 6-item review gets acted on.

  • Blocker: ship this and something breaks — data, auth, contracts, runtime
  • Major: real maintenance cost, will bite within weeks
  • Minor: cumulative drag — worth a cleanup pass
  • Nit: preference, subjective, author's call

If you find yourself marking everything Major, recalibrate. If everything is Nit, you're not looking hard enough.

What NOT to do

  • Don't rewrite the code yourself unless the user asked. Point at the problem and suggest the fix direction — let the author own the edit.
  • Don't file-by-file walk through everything. Group findings by severity, not by file.
  • Don't invent issues to pad the review. Empty sections are fine. "Looks good" is a valid outcome.
  • Don't quote huge blocks of the reviewed code back at the author. They wrote it. A file:line ref is enough.
  • Don't moralize. "This is bad practice because..." reads worse than "This will break when X happens — do Y instead."
  • Don't review stylistic preferences outside the guide as if they were rules. Mark taste items as Nits and move on.

Process

  1. Establish scope: which files/diff. If unclear, default to git diff main...HEAD.
  2. Skim the full diff once before forming opinions. Avoid first-impression tunnel vision.
  3. Read surrounding context for any file with meaningful changes — the call sites, the types, the tests.
  4. Consult references/style-guide.md when a finding touches a specific principle; cite the section so the author can drill in.
  5. Draft findings, then cut by 30% — remove anything that wouldn't survive the author asking "so what?".
  6. Output the report in the format above.

The goal: the author reads the review, knows exactly what to do next, and feels the reviewer actually understood the code.