Alembicalembic
← Back to Skills

Effective Code Review

stable

List of review comments with file locations

Edit on GitHub
Version1.0.0
Last Reviewed2026-01-05
Compatible Withcopilot, cursor, claude
reviewtesting

Inputs

Outputs

Effective Code Review

A structured approach to reviewing pull requests that catches bugs and improves code quality.

Purpose

Code review is a critical quality gate. Done well, it catches bugs early, shares knowledge across the team, and maintains code standards. This skill provides a systematic approach to reviewing PRs efficiently and constructively.

Prerequisites

  • Access to the repository and PR

  • Familiarity with the codebase area being changed

  • Understanding of project conventions and standards

    • Steps

    Step 1: Understand the Context

    Before looking at code, understand what and why.

    Read:
    1. PR title and description
    2. Linked issue or ticket
    3. Any design documents referenced

    Expected outcome: Clear understanding of the change's purpose.

    Step 2: High-Level Pass

    Skim the entire diff to understand scope and approach.

    Ask yourself:
  • Is the approach reasonable?

  • Is the scope appropriate (not too big)?

  • Are there any obvious architectural concerns?

    • Expected outcome: Mental model of the change structure.

    Step 3: Detailed Review

    Go file by file, checking for:

    Correctness

  •  Logic handles edge cases

  •  Error handling is appropriate

  •  No off-by-one errors

  •  Null/undefined checks present
    • Security

  •  No hardcoded secrets

  •  Input validation present

  •  SQL injection / XSS prevented

  •  Auth checks in place
    • Maintainability

  •  Code is readable

  •  Functions are focused

  •  Naming is clear

  •  Comments explain "why", not "what"
    • Testing

  •  Tests cover happy path

  •  Tests cover edge cases

  •  Tests are maintainable

    • Expected outcome: List of specific, actionable comments.

    Step 4: Write Constructive Feedback

    Frame comments helpfully:

    Good comment patterns:
    "Consider using X instead of Y because..."
    "What happens if Z is null here?"
    "Nice solution! One suggestion: ..."
    "Nit: formatting" (prefix minor issues)
    Avoid:

    "This is wrong"
    "Why did you do this?"
    "I would never..."

    Expected outcome: Comments that teach and improve.

    Checks

    Automated Checks

    Ensure CI passes before human review

    Check: tests pass, lint passes, build succeeds

    Manual Checks

  • All comments are constructive

  • Blocking issues clearly marked

  • Approval only given when confident

    • Failure Modes

    SymptomCauseResolution

    Review takes hoursPR too largeAsk author to split
    Missing obvious bugsRushed reviewTake breaks, use checklist
    Author defensiveHarsh feedbackReframe constructively
    BikesheddingFocus on style over substanceLet go of minor preferences

    Rollback

    If a bug slips through review:

    1. Don't blame the reviewer or author
    2. Fix the bug first
    3. Analyze: What category of bug was it?
    4. Update review checklist to catch similar issues

    Variations

    Quick Review (< 50 lines)

    - Skim context
  • Check for obvious issues

  • Approve or comment quickly

  • Don't overthink small changes

    • Large Review (> 500 lines)

    - Request PR split if possible
  • Review in multiple sessions

  • Focus on architecture first

  • Use "Request changes" early if fundamentally flawed

    • Related Skills

  • [Git Workflow](../git-workflow/SKILL.md) - PR creation best practices

  • [Testing Strategy](../testing-strategy/SKILL.md) - What tests to expect

    • References

  • [Google Code Review Guidelines](https://google.github.io/eng-practices/review/)

  • [Conventional Comments](https://conventionalcomments.org/)