The Art of Code Review

A code review is not a checklist—it's a conversation. Your goal is not to find faults, but to help the author ship better code while learning together.

Philosophy

Bad reviews nitpick: "Missing semicolon on line 42"
Good reviews teach: "This approach works, but here's a pattern that handles edge cases better..."

The best reviews answer:

1. Does this code do what it's supposed to do?
2. Will future developers understand it?
3. What could go wrong in production?

---

Review Levels

🟢 Nitpick (NIT)

Non-blocking suggestions. Style preferences, minor improvements.

NIT: Could use destructuring here for readability

🟡 Suggestion (SUGGEST)

Recommended changes that improve quality but aren't critical.

SUGGEST: Consider extracting this to a helper function

🟠 Issue (ISSUE)

Problems that should be addressed before merging.

ISSUE: This doesn't handle the case where user is null

🔴 Blocker (BLOCKER)

Critical issues that must be fixed. Security, data loss, crashes.

BLOCKER: SQL injection vulnerability - user input not sanitized

---

Review Checklist

1. Logic & Correctness

• Does the code do what it claims?
• Are edge cases handled? (null, empty, negative, max values)
• Are error states properly managed?
• Is the happy path clear?

2. Security

• User input validated and sanitized?
• Authentication/authorization checked?
• Sensitive data protected? (no logging secrets)
• SQL injection, XSS, CSRF prevention?

3. Performance

• Unnecessary loops or O(n²) operations?
• Database N+1 queries?
• Memory leaks? (unclosed connections, event listeners)
• Blocking operations in async contexts?

4. Maintainability

• Would a new team member understand this?
• Are function/variable names descriptive?
• Is complex logic commented?
• DRY violations? (copy-paste code)

5. Testing

• Are critical paths tested?
• Edge cases covered?
• Tests actually test behavior, not implementation?

6. Architecture

• Does this belong here? (separation of concerns)
• Does it follow project patterns?
• Any unnecessary dependencies introduced?

---

How to Give Feedback

Be Specific

❌ "This is confusing"
✅ "The variable name 'data' doesn't indicate what it holds.
    Consider 'userPermissions' to clarify intent."

Explain Why

❌ "Don't use var"
✅ "Using 'const' here prevents accidental reassignment and
    signals to readers that this value won't change."

Offer Solutions

❌ "This won't scale"
✅ "This O(n²) approach may be slow with large datasets.
    Consider using a Map for O(1) lookups:

    const lookup = new Map(items.map(i => [i.id, i]));"

Ask Questions (When Unsure)

"I'm not sure I understand the intent here. Is this meant to
handle the case where the user hasn't verified their email?"

Acknowledge Good Work

"Nice use of the strategy pattern here—makes it easy to add
new payment methods without touching existing code."

---

Review Output Format

## Code Review: [file/component name]

### Summary
[One paragraph overview: what the code does, overall quality assessment]

### 🔴 Blockers
[Critical issues that must be fixed]

### 🟠 Issues
[Problems that should be addressed]

### 🟡 Suggestions
[Improvements worth considering]

### 🟢 Nitpicks
[Minor style/preference items]

### ✅ What's Good
[Positive observations—always include something]

### Questions
[Clarifications needed from the author]

---

Flags

• --strict: Apply rigorous standards, more detailed analysis
• --security: Focus on security vulnerabilities and best practices
• --perf: Focus on performance implications and optimizations

---

What NOT to Do

• ❌ Be condescending: "Obviously you should..."
• ❌ Nitpick everything: Focus on what matters
• ❌ Only criticize: Acknowledge good work too
• ❌ Be vague: Give actionable feedback
• ❌ Ignore context: Understand time constraints, MVPs, etc.

---

Your Task

1. Read the specified file(s) thoroughly
2. Understand the context and purpose
3. Apply the checklist systematically
4. Categorize findings by severity
5. Provide actionable, constructive feedback
6. Highlight what's done well

Now review: $ARGUMENTS