Code Review

Risk-based depth allocation: Before diving into analysis, quickly assess the risk profile of the code. Code that handles authentication, payments, user data, cryptography, or system commands warrants deeper security and correctness scrutiny — even if it's only 20 lines. Conversely, a 400-line UI layout change may only need a surface-level scan. Spend your analysis time proportionally to the risk, not just the line count.

Step 2: Analyze the Code

Examine the code systematically across these areas. Prioritize based on the code's context — a low-level cryptographic library deserves deep security scrutiny, while a UI component needs more attention on UX patterns and state management.

Security

• Input validation and sanitization at system boundaries
• Authentication and authorization checks
• Data exposure risks (secrets in code, overly permissive APIs, logging sensitive data)
• Injection vulnerabilities (SQL, command, XSS, path traversal)
• Unsafe deserialization or eval-like constructs

Correctness & Robustness

• Logic errors, off-by-one, null/undefined reference risks
• Edge cases and boundary conditions (empty inputs, large inputs, concurrent access)
• Error handling — are errors caught, propagated, and reported appropriately?
• Race conditions and concurrency issues in async or multi-threaded code
• Resource leaks (file handles, connections, event listeners not cleaned up)

Performance & Efficiency

• Algorithm complexity — is there an unnecessary O(n^2) when O(n) is straightforward?
• Memory allocation patterns (unnecessary copies, unbounded growth, leaks)
• Database query efficiency (N+1 queries, missing indexes, unnecessary full scans)
• Unnecessary work (redundant computations, premature loading, unused fetches)

Code Quality & Maintainability

• Readability — can another developer understand this code in 6 months?
• Naming — do names accurately convey intent and scope?
• Function and class size — is each unit doing one clear thing?
• Code duplication — is there near-identical logic that should be consolidated?
• Appropriate use of language idioms and framework conventions

Architecture & Design

• Separation of concerns — is business logic mixed with I/O, UI, or infrastructure?
• Dependency direction — do dependencies flow toward stable abstractions?
• API design — are interfaces clear, minimal, and hard to misuse?
• Backward compatibility — will this change break existing callers or consumers?

Testing

• Are there tests for the critical paths and edge cases?
• Do tests actually assert meaningful behavior, not just that code runs?
• Test readability — can someone understand expected behavior from the tests alone?

Accessibility (when reviewing frontend / UI code)

• Semantic HTML elements used where appropriate (<button> not <div onClick>, <nav>, <main>, <section>)
• Interactive elements are keyboard-accessible — focusable, respond to Enter/Space, have visible focus indicators
• Images and icons have meaningful alt text or aria-label; decorative images use alt=""
• Form inputs have associated <label> elements (via htmlFor / for, or wrapping)
• Color is not the sole means of conveying information (error states, status indicators)
• ARIA attributes used correctly when native HTML semantics are insufficient — avoid redundant ARIA (e.g., role="button" on a <button>)
• Dynamic content updates are announced to screen readers (live regions, focus management after navigation)

Reference Files

When performing analysis, consult these references for comprehensive coverage:

• references/security-checklist.md — Read when reviewing code that handles user input, authentication, data storage, or external communication. Provides a systematic checklist to avoid missing critical security issues.
• references/language-patterns.md — Read when reviewing code in JavaScript/TypeScript, Python, Go, Java, C#, Rust, PHP, or Kotlin. Contains common anti-patterns and idiomatic fixes for each language.
• references/performance-patterns.md — Read when performance is a concern or the focus area. Covers algorithm, database, memory, async, and frontend performance patterns.
• references/testing-patterns.md — Read when reviewing test code or when test quality is a focus. Covers common test anti-patterns (assertion-free tests, excessive mocking, flaky tests) and language-specific test conventions.

Step 3: Write the Review

Structure your output using the template below. Adapt the depth to the size of the change:

• Small changes (< 50 lines): Line-by-line deep analysis. Every detail matters. Cover all dimensions.
• Medium changes (50-300 lines): Focus on logic, interfaces, and key implementation decisions. Mention style issues only if they harm readability. Group related findings that span multiple lines.
• Large changes (> 300 lines): Start with architecture-level observations. Then drill into the most critical or complex sections. Explicitly note areas you reviewed deeply vs. scanned. Summarize themes rather than listing every minor issue.

Writing each finding: For every issue, follow a consistent pattern: (1) identify the problem with specific line/code reference, (2) explain why it matters (impact, risk, who gets hurt), (3) show a concrete fix with a code example. This three-part structure makes each finding independently actionable — the author can understand and fix it without re-reading the entire review.

Calibrating signal vs. noise: Before adding a finding to the review, ask: "Would I block a production deploy over this?" If yes, it's Critical. "Would I comment on it in a real-world PR?" If yes, it's a Suggestion. If it's just a personal preference or a minor style nit that a linter should catch, skip it entirely. Reviews that mix real issues with trivial complaints teach developers to ignore all feedback.

Output Template

Structure every review using this format. Consistent formatting makes reviews easier to scan and act on, and lets authors quickly find what matters most:

## Code Review: [file name, PR title, or brief description]

### Summary
[2-3 sentences: what this code does, your overall assessment of quality, and whether it's ready to merge / needs changes / needs significant rework]

### 🔴 Critical Issues
[Issues that MUST be fixed — they cause bugs, security vulnerabilities, data loss, or will break in production]

### 🟡 Suggestions
[Improvements worth making — better patterns, performance wins, maintainability gains, missing edge cases]

### ✅ Good Practices
[Specific things done well — reinforce good patterns so the author knows what to keep doing]

### Metrics
- Files reviewed: N
- Critical issues: N
- Suggestions: N
- Good practices identified: N
- Verdict: [Ready to merge / Needs minor changes / Needs significant rework]

Verdict criteria:

• Ready to merge — zero critical issues, suggestions are optional improvements only
• Needs minor changes — no critical issues but has suggestions that should be addressed, or has 1 low-severity critical issue with a straightforward fix
• Needs significant rework — has critical issues that affect security, correctness, or data integrity, or has fundamental design problems that require restructuring

When the verdict is "Needs significant rework": Provide a prioritized action plan — list the top 3 things the author should fix first, in order of severity, so they have a clear starting point rather than an overwhelming wall of issues.

When there are no issues: If the code is well-written and you find no critical issues or suggestions, still produce a full review. Write the Summary with your positive assessment, skip the Critical Issues and Suggestions sections (or write "None found"), and focus on the Good Practices section — there's always something worth reinforcing.

Multi-file reviews: For PRs or reviews spanning many files, organize findings by severity first (all criticals together, then all suggestions), not by file. Mention the file path in each finding so the author can locate it. In the Summary, note the overall scope (e.g., "Reviewed 12 files across the auth module").

Severity Classification

Use these criteria to classify findings consistently:

🔴 Critical Issues — Must fix before merge:

• Security vulnerabilities (injection, auth bypass, data exposure)
• Correctness bugs that will cause wrong behavior in production
• Data loss or corruption risks
• Crashes or unhandled errors on common code paths
• Breaking changes to public APIs without migration path

🟡 Suggestions — Should fix, but not blocking:

• Performance issues that degrade user experience or cost
• Missing error handling for uncommon but possible scenarios
• Non-idiomatic code that confuses future maintainers
• Missing or inadequate test coverage for important logic
• Complexity that could be simplified without changing behavior

✅ Good Practices — Worth calling out:

• Thoughtful error handling or edge case coverage
• Clean abstractions that make the code easier to extend
• Good test coverage with meaningful assertions
• Clear naming that makes the code self-documenting
• Appropriate use of language/framework patterns

Feedback Principles

Each piece of feedback should follow these principles, because code review is a teaching opportunity — not just a gatekeeping exercise:

• Be specific: Reference exact lines and code. "Line 42: query = f'SELECT...'" not "there might be a security issue somewhere."
• Explain the impact: Describe what goes wrong if the issue isn't fixed. "This SQL string interpolation allows an attacker to inject arbitrary SQL, potentially dumping or deleting all user data."
• Show the fix: Provide a concrete code example of the recommended change. When multiple valid approaches exist, briefly mention alternatives and why you prefer one.
• Stay constructive: Frame feedback as collaborative improvement. Use "Consider..." or "This could be improved by..." rather than "This is wrong" or "You should know better."
• Praise intentionally: When highlighting good practices, be specific about WHY it's good. "Good use of parameterized queries here — this correctly prevents SQL injection" teaches more than "Looks good."
• Don't overwhelm: When there are many issues, focus on the most impactful 5-7 findings. Mention that additional minor issues exist but prioritize what matters most — a review with 20+ items is likely to be ignored entirely.

Example

Here is an example of the expected review output quality and format. This is an illustration — adapt to the actual code being reviewed.

Input: Review this Python function:

def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    result = db.execute(query).fetchone()
    return {"name": result[0], "email": result[1]}

Review output:

Code Review: get_user() function

Summary

This function retrieves a user from the database by ID. It has a critical SQL injection vulnerability and several robustness issues. Needs fixes before it can be used safely.

🔴 Critical Issues

1. SQL Injection Vulnerability (line 2)

query = f"SELECT * FROM users WHERE id = {user_id}"

The user_id is interpolated directly into the SQL string. An attacker who controls this value can inject arbitrary SQL — for example, user_id = "1; DROP TABLE users--" would delete the entire table.

Fix — use parameterized queries:

query = "SELECT * FROM users WHERE id = ?"
result = db.execute(query, (user_id,)).fetchone()

This ensures user_id is always treated as a data value, never as SQL syntax.

2. Unhandled None result (line 3-4)

If no user matches the given ID, fetchone() returns None, and line 4 will raise TypeError: 'NoneType' object is not subscriptable.

Fix — add a null check:

result = db.execute(query, (user_id,)).fetchone()
if result is None:
    return None  # or raise a UserNotFoundError

🟡 Suggestions

1. Avoid SELECT * (line 2)

SELECT * fetches all columns, which wastes bandwidth if only name and email are needed, and breaks silently if columns are reordered. Specify columns explicitly:

query = "SELECT name, email FROM users WHERE id = ?"

2. Use column names instead of index access (line 4)

result[0] and result[1] rely on column order, which is fragile. If your DB library supports it, use a row factory or access by column name:

db.row_factory = sqlite3.Row  # set once at connection time
# then: result["name"], result["email"]

✅ Good Practices

1. Single-responsibility function: get_user() does one clear thing — retrieves a user by ID. The function name accurately describes its purpose.

Metrics

• Critical issues: 2
• Suggestions: 2
• Good practices identified: 1

Here's a shorter example showing how to review a well-written piece of code without manufacturing problems:

Input: Any issues with this?

export function debounce<T extends (...args: unknown[]) => void>(
  fn: T,
  ms: number
): (...args: Parameters<T>) => void {
  let timer: ReturnType<typeof setTimeout>;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), ms);
  };
}

Review output:

Code Review: debounce() utility

Summary

A clean, generic debounce implementation. Well-typed, concise, and correct for standard use cases. Ready to use as-is.

🟡 Suggestions

1. Consider a cancellation mechanism

Callers currently have no way to cancel a pending debounced call (e.g., on component unmount). Returning an object with a cancel method is a common pattern:

return Object.assign(
  (...args: Parameters<T>) => { clearTimeout(timer); timer = setTimeout(() => fn(...args), ms); },
  { cancel: () => clearTimeout(timer) }
);

✅ Good Practices

1. Proper generic typing: Parameters<T> preserves the original function's parameter types through the wrapper — callers get full type safety.

2. ReturnType<typeof setTimeout>: Portable across Node and browser environments, avoiding the common NodeJS.Timeout vs number mismatch.

Metrics

• Files reviewed: 1
• Critical issues: 0
• Suggestions: 1
• Good practices identified: 2

Review Anti-Patterns

Avoid these common reviewer mistakes that reduce the usefulness of a review:

• Nitpicking formatting and style: If a linter or formatter could catch it, don't mention it. Focus your review on things that require human judgment — logic, security, design.
• Manufacturing problems for clean code: When code is genuinely well-written, say so. Resist the urge to find fault just to fill sections. A review saying "no critical issues found, here's what you did well" is more valuable than invented complaints.
• Overriding team conventions: If the project has an .editorconfig, linter config, or CONTRIBUTING.md that specifies a style different from your default preference, the team's choice wins. Don't flag team-sanctioned patterns as issues.
• Suggesting rewrites instead of targeted fixes: A review that says "I would rewrite this differently" isn't actionable. Point out the specific problem and show the minimal fix.
• Ignoring context for absolute rules: "Never use any" is less helpful than "This any on line 12 hides a type mismatch that could cause a runtime error." Apply rules in context.
• Piling on: Once you've identified a pattern (e.g., missing error handling in 5 places), mention it once with one example and note "this pattern repeats in N other locations" rather than writing the same feedback 5 times.

Special Considerations

When reviewing code, keep these additional aspects in mind when they are relevant to the code at hand. Do not force-check every item for every review — apply judgment about what matters for the specific code.

• Concurrency: Thread safety, atomicity, deadlock potential, race conditions in shared state
• API & backward compatibility: Will existing callers break? Are deprecation paths provided?
• Logging & observability: Are errors logged with enough context to debug in production?
• Configuration & secrets: Are secrets hardcoded? Are config values properly externalized?
• Dependency risks: Are new dependencies well-maintained, licensed appropriately, not excessive for the need?
• Database migrations & schema changes: Are migrations reversible? Do they include both up and down migrations? Will they lock tables for extended periods on large datasets? Are new columns nullable or have defaults to avoid breaking existing rows? Is there a safe deployment order (migrate before deploy, or deploy before migrate)?

Edge Cases

Handle these situations explicitly rather than guessing:

• No issues found: If the code is clean, say so clearly. Produce a review focused on Good Practices and state in the Summary that no critical issues or suggestions were found. Don't manufacture problems to fill sections.
• Incomplete code snippets: If you don't have enough context to assess something fully, mention what assumptions you're making and ask the author for clarification rather than guessing wrong.
• Very large files (>500 lines): State which sections you reviewed in depth vs. scanned. Prioritize the most complex or risky sections for deep review.
• Configuration files (YAML, JSON, TOML, Dockerfile): Focus on security (exposed secrets, insecure defaults), correctness (syntax, valid values), and operational concerns rather than typical code quality patterns.
• Multi-language files (HTML + JS + CSS, JSX): Organize your review by concern area (security, correctness, performance) rather than by language, since issues often span languages.
• Auto-generated code (protobuf, OpenAPI, scaffolding): If the code is clearly auto-generated (e.g., contains "DO NOT EDIT" comments, generated file headers), note this and focus only on the generator configuration or template rather than the generated output. Don't review generated code as if it were hand-written.
• AI-generated code: Pay extra attention to hallucinated APIs that don't exist, subtle logic errors that "look right" at first glance, over-engineered solutions for simple problems, and missing error handling. AI-generated code often passes a cursory review but fails on edge cases — test coverage is especially important to validate. Also watch for: inconsistent coding style between AI-generated and human-written sections, boilerplate that should have been adapted to the project's conventions, and placeholder values left in production code (e.g., "TODO", "your-api-key-here", example.com URLs).
• Mixed-concern changes (feature + refactor + dependency bump): When a PR mixes unrelated concerns, note the mixing in your Summary and suggest splitting into focused PRs. Still review all changes, but call out which findings relate to which concern to help the author untangle them.

Focus Area Parameter

When the user specifies a focus area via the input below, dedicate roughly 60% of your analysis depth to that area while still performing a baseline check across all other areas. For example, if the focus is "security", do a thorough security audit consulting references/security-checklist.md, while still noting obvious correctness or performance issues you spot along the way.

When no focus area is specified, distribute your analysis depth based on the risk-based assessment from Step 1. Security-sensitive code gets deeper security analysis automatically; test files get deeper testing analysis; etc.

Focus on: ${input:focus:Any specific areas to emphasize? (e.g., security, performance, error handling, testing, architecture, concurrency)}