bjg4/code-review

Code Review Skill

Purpose and Use Cases

This skill helps developers review code effectively. Code review is a collaborative process where experienced developers examine changes to catch issues before they reach production.

Use cases:

• A developer wants to review a pull request before approving it so they can catch bugs early.
• A team lead wants consistent review quality across the team so feedback is actionable.
• A security-conscious developer wants to scan changes for vulnerabilities so the codebase stays safe.

Why Structured Reviews Matter

Unstructured reviews miss critical issues because reviewers jump around without a system. Structured findings with severity levels help authors prioritize fixes. Explaining why something is a problem teaches the team and reduces repeat mistakes.

Review Process

When reviewing code, work through these areas in order because security and correctness issues outweigh style nits:

1. Correctness and Logic

Look for off-by-one errors, null handling, race conditions, and missing edge cases. Ask whether the change handles failure paths.

2. Security

Examine input validation, authentication, authorization, secrets handling, and injection risks (SQL, XSS, command injection). Security issues should be flagged as high severity because they can cause real harm.

3. Maintainability

Consider naming clarity, function length, duplication, test coverage, and whether the change fits existing patterns. Maintainability affects long-term velocity.

4. Performance

Note obvious inefficiencies — N+1 queries, unnecessary allocations, blocking calls in hot paths — when relevant to the change.

Output Format

Produce structured findings grouped by severity:

• Critical — must fix before merge (security, data loss, broken behavior)
• Major — should fix (logic bugs, missing error handling)
• Minor — nice to fix (style, naming, small refactors)

Each finding should include: location (file/line if available), description of the issue, and a suggested fix or direction.

Communication Style

Be constructive. Explain reasoning so the author learns. Avoid vague comments like "this is wrong" without saying why.

When Things Go Wrong

If the diff or code context is missing, ask the user to provide it. If the request is outside review scope (e.g., writing new features from scratch), explain that and offer to switch tasks.

Degrees of Freedom

Adapt review depth to the change size — a one-line typo fix needs a lighter pass than a new auth module. Match the user's stated priorities (security-heavy vs speed-heavy) when they indicate them.

Examples

Good finding: "Line 42: SQL query uses string interpolation with user input — SQL injection risk. Use parameterized queries."

Weak finding: "Security could be better."