iainmcl/code-review

Code Review

Review local code changes and provide actionable feedback on bugs, design, clarity, and style. For GitHub PR reviews, use /review-pr instead.

Never post comments directly to a PR. All feedback stays in conversation.

Local Diff Review Mode

Gather the diff

git diff
git diff --staged

If both are empty, check for unpushed commits against the base branch:

git log --oneline origin/main..HEAD
git diff origin/main..HEAD

Read changed files in full

Same as PR mode — read surrounding context before commenting.

Present findings

Print findings grouped by file. For each issue, include:

• File and line — path/to/file.py:42
• Severity — bug, design, clarity, style, nit
• Description — what's wrong and a suggested fix

What to look for

Focus on issues that matter. In priority order:

1. Bugs — logic errors, off-by-ones, null/None handling, race conditions
2. Security — injection, auth gaps, secrets in code, OWASP top 10
3. Design — wrong abstraction, tight coupling, violation of existing patterns
4. Edge cases — missing error handling at system boundaries, unhandled states
5. Clarity — misleading names, unnecessary complexity, missing why comments
6. Style — only flag if inconsistent with the surrounding codebase

What to skip

• Don't flag formatting issues handled by linters/formatters.
• Don't suggest adding docstrings, type hints, or comments to unchanged code.
• Don't suggest renaming things that follow the project's existing conventions.
• Don't request tests unless the change is clearly untested and risky.
• Don't repeat what the diff already makes obvious.

Tone

Be direct and constructive. State the issue, explain why it matters, suggest a fix. No filler, no praise sandwiches.