home / skills / vadimcomanescu / codex-skills / code-reviewer

code-reviewer skill

safe

This skill provides structured code-review guidance to improve correctness, safety, maintainability, performance, and tests in diffs and pull requests.

npx playbooks add skill vadimcomanescu/codex-skills --skill code-reviewer

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.0 KB

---
name: code-reviewer
description: "High-signal code review workflow for pull requests and patches: correctness, readability, API/UX, performance, security, and maintainability. Use when reviewing diffs/PRs, writing review comments, proposing fixes, or producing a structured review report with actionable follow-ups."
---

# Code Reviewer

Give reviews that help the author ship safely and quickly.

## Quick Start
1) Understand intent: what’s the user-facing / system-facing change and why?
2) Review in this order:
   - Correctness (edge cases, invariants, error handling)
   - Safety (security + data handling + secrets)
   - Maintainability (structure, naming, interfaces)
   - Performance (hot paths, I/O, allocations, DB queries)
   - Tests (do they fail before the fix? do they cover the right behavior?)
3) Leave comments that are:
   - **Actionable** (what to change) + **why** (risk/benefit) + **scope** (must vs nice-to-have)

## Large diff triage (use when the change is big)
- Start with the entrypoints and high-risk files (auth, payments, data writes).
- Identify invariants the change must preserve, then hunt for violations.
- Skim for mechanical changes and collapse them; focus deep review on behavioral deltas.

## When to request changes
- Bugs or correctness issues that can ship user-impacting failures.
- Security/privacy regressions or data handling gaps.
- Missing or inadequate tests for new behavior or fixed bugs.

## Output format (recommended)
- **Summary**: what the change does
- **Major issues**: must-fix items (blockers)
- **Minor suggestions**: improvements / nits
- **Test plan**: how to validate locally/CI
- **Follow-ups**: tickets/cleanup that shouldn’t block merge

## Optional tool: generate a review report from git diff
From the repo you’re reviewing:
```bash
python ~/.codex/skills/code-reviewer/scripts/review_diff.py --base origin/main --out /tmp/review.md
```

## References
- Review checklist and comment style: `references/review-checklist.md`

Overview

This skill provides a high-signal code review workflow tailored for pull requests and patches, focusing on correctness, readability, API/UX, performance, security, and maintainability. It helps reviewers triage large diffs, produce structured review reports, and write actionable comments that help teams ship safely and quickly. The guidance is language-agnostic but optimized for Python repositories. Use it to generate review checklists, pinpoint blockers, and propose concrete fixes.

How this skill works

I inspect diffs and PRs by first understanding the change intent and scope, then applying a prioritized review order: correctness, safety, maintainability, performance, and tests. For large changes I triage entrypoints and high-risk files, identify invariants, and focus deep review on behavioral deltas while collapsing mechanical edits. Outputs include a concise summary, major issues, minor suggestions, a test plan, and follow-up actions.

When to use it

Reviewing pull requests or patches that change behavior, APIs, or data handling.
Triage large diffs to find high-risk files and invariant violations quickly.
Writing review comments that must be actionable and explain risk/benefit.
Preparing a structured review report for engineering leads or release notes.
Evaluating tests to ensure new behavior is covered and regressions are prevented.

Best practices

Start by documenting the change intent and the invariants it must preserve.
Follow the review order: correctness → safety → maintainability → performance → tests.
Prioritize blocking issues (security, correctness) and mark everything else as suggestions.
Keep comments actionable: what to change, why it matters, and whether it’s blocking.
For large diffs, review entrypoints and risky modules first, skip bulk mechanical edits.

Example use cases

Generate a review report from a git diff that highlights blockers and a local test plan.
Write precise PR comments suggesting code fixes, patches, or alternative APIs.
Triage a multi-file refactor to ensure invariants and data handling remain correct.
Assess performance risks in hot paths and recommend targeted benchmarks or fixes.
Identify missing tests for edge cases and propose concrete test cases to add.

FAQ

How do I decide what’s a blocker?

Blockers are issues that lead to incorrect behavior, data loss, security/privacy regressions, or production crashes. Anything that risks user-facing failures or sensitive data exposure should block merge.

What level of detail should review comments include?

Include an explicit action, a short rationale (risk/benefit), and scope (must-fix vs nice-to-have). For complex fixes, sketch the minimal code change or link to a suggested patch.