Code Review Philosophy

TL;DR

Systematic code review across 4 layers with severity classification. Only report findings with ≥80% confidence. Include file:line references for all issues.

When to Use This Skill

• Before reporting implementation completion

• When explicitly asked to review code

• When using the /review command

• As an independent audit after code changes

The 4 Review Layers

Layer 1: Correctness

• Logic errors and edge cases

• Error handling completeness

• Type safety and null checks

• Algorithm correctness

• Off-by-one errors

Layer 2: Security

• No hardcoded secrets or API keys

• Input validation and sanitization

• Injection vulnerability prevention (SQL, XSS, command)

• Authentication and authorization checks

• Sensitive data not logged

• OWASP Top 10 awareness

Layer 3: Performance

• No N+1 query patterns

• Appropriate caching strategies

• No unnecessary re-renders (React/frontend)

• Lazy loading where appropriate

• Memory leak prevention

• Algorithmic complexity concerns

Layer 4: Style & Maintainability

• Adherence to project conventions (check AGENTS.md)

• Code duplication (DRY violations)

• Complexity management (cyclomatic complexity)

• Documentation completeness

• Test coverage gaps

Severity Classification

Severity Icon Criteria Action Required

Critical 🔴 Security vulnerabilities, crashes, data loss, corruption Must fix before merge

Major 🟠 Bugs, performance issues, missing error handling Should fix

Minor 🟡 Code smells, maintainability issues, test gaps Nice to fix

Nitpick 🟢 Style preferences, naming suggestions, documentation Optional

Confidence Threshold

Only report findings with ≥80% confidence.

If uncertain about an issue:

• State the uncertainty explicitly: "Potential issue (70% confidence): ..."

• Suggest investigation rather than assert a problem

• Prefer false negatives over false positives (reduce noise)

Review Process

• Initial Scan - Identify all files in scope, understand the change

• Deep Analysis - Apply all 4 layers systematically to each file

• Context Evaluation - Consider surrounding code, project patterns, existing conventions

• Philosophy Check - Verify against code-philosophy (5 Laws) if applicable

• Synthesize Findings - Group by severity, deduplicate, prioritize

Output Format

Structure your review as:

• Files Reviewed - List all files analyzed

• Overall Assessment - APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION

• Summary - 2-3 sentence overview

• Critical Issues (🔴) - With file:line references

• Major Issues (🟠) - With file:line references

• Minor Issues (🟡) - With file:line references

• Positive Observations (🟢) - What's done well (always include at least one)

• Philosophy Compliance - Checklist results if applicable

What NOT to Do

• Do NOT report low-confidence findings as definite issues

• Do NOT provide vague feedback without file:line references

• Do NOT skip any of the 4 layers

• Do NOT forget to note positive observations

• Do NOT modify any files during review

• Do NOT approve without completing the full review process

Adherence Checklist

Before completing a review, verify:

• All 4 layers analyzed (Correctness, Security, Performance, Style)

• Severity assigned to each finding

• Confidence ≥80% for all reported issues (or uncertainty stated)

• File names and line numbers included for all findings

• Positive observations noted

• Output follows the standard format