| name | software-code-review |
| description | Applies systematic code review patterns and checklists. Use when reviewing PRs or diffs for correctness, security, readability, maintainability, and AI-generated changes. |
| compatibility | Portable core. Works on Claude Code and Codex. |
| version | 1.1 |
| last_validated | 2026-07-11T00:00:00.000Z |
Code Review
This skill is for reviewing existing changes. It routes the agent to the right checklist, review mode, and platform workflow without turning SKILL.md into a tool catalog.
Quick Reference
| Task | Use | Primary Reference |
|---|
| General PR or diff review | Baseline review flow and severity rubric | references/operational-playbook.md |
| AI-generated or agent-created changes | Human-in-the-loop review rules and platform controls | references/automation-tools.md |
| Building or tuning an AI review tool/integration | Pre-review deterministic gate, size-gated planning pass, self-refutation filter pass | references/deterministic-vs-llm-routing.md |
| Backend/API review | Error handling, contracts, persistence, operability | assets/backend-api/api-review.md |
| Frontend review | Accessibility, responsive behavior, Core Web Vitals | assets/web-frontend/frontend-review.md |
| Mobile review | Platform patterns, lifecycle, permissions, UX | assets/mobile/mobile-review.md |
| Infrastructure review | CI/CD, IaC, secrets, deploy safety | assets/infrastructure/infrastructure-review.md |
| Smart contract review | Access control, reentrancy, unsafe assumptions | assets/blockchain/crypto-review.md |
| Data / ML review | Pipelines, experiments, models, deployment | assets/data-ml/data-pipeline-review.md |
When to Use This Skill
Use this skill when the primary task is to:
- review a PR, merge request, or diff
- find correctness, security, reliability, or maintainability issues
- assess test gaps and regression risk
- critique AI-generated or agent-created changes before merge
- recommend small, behavior-preserving refactors
When NOT to Use This Skill
Workflow
- Confirm the review surface: diff, PR, merge request, generated code, or a focused file set.
- Route architecture-only or formal security-design questions to the adjacent skill when review is not the primary task.
- Apply review modes in order: correctness, security, reliability, performance, and maintainability.
- Pull in the stack overlay only when the code actually needs that domain-specific lens.
- Return concrete findings with evidence, then verify any platform-specific claims via the navigation sources.
ASCII Flow
Code review request
-> Identify diff, scope, and expected behavior
-> Trace changed control flow and data contracts
-> Look for regressions, security, performance, and test gaps
-> Rank findings by severity and confidence
-> Cite exact files and lines
-> Summarize residual risk and verification gaps
Review Routing
Apply review modes in this order unless the user asks for a narrower scope:
- Correctness and edge cases
- Security and data handling
- Reliability and operability
- Performance and cost
- Maintainability and test coverage
Stack overlays:
Platform overlays:
- GitHub: Copilot review, repository instructions, excluded files, Code Quality, merge queue
- GitLab: Duo review instructions, merge request approvals, approval rules
- Bitbucket: Code Insights, branch restrictions, required checks
If the user asks a platform-specific automation question, open the official entries in data/sources.json first and use references/automation-tools.md.
AI-Assisted Review Rules
- Human review is authoritative. AI findings are advisory until confirmed.
- Treat AI-generated code and agent-created PRs as higher-context review tasks, not lower-effort review tasks: the bottleneck moves from writing to verifying, so budget reviewer time accordingly rather than assuming automation shrinks the review workload.
- Judge AI-generated code against this codebase's actual conventions, not an abstract style guide — consistency with surrounding code is the more useful bar than "is this idiomatic in general."
- Prefer native platform controls before third-party bots:
- repository or path-specific review instructions
- excluded files / generated file filters
- required checks, approval rules, and merge queues
- Do not accept benchmark, pricing, or feature-comparison claims from memory. Verify current tool status first — this space (GitHub Copilot code review, CodeRabbit, Qodo/PR-Agent, and adjacent tools) changes ownership, pricing, and capability frequently; see
references/automation-tools.md and data/sources.json and re-verify before quoting specifics.
- Never pin or cite a specific AI model version/ID as a reviewer-facing fact; capability and behavior shift too fast for that to stay true.
AI-Generated Code Review Checklist
Apply these checks when reviewing AI-generated code or agent-created PRs:
| Check | What to look for |
|---|
| Hallucinated imports | Packages or methods that don't exist; verify with npm info / pip index |
| Stale APIs | Deprecated methods, old signatures, removed features |
| Security gaps | Missing input validation, hardcoded secrets, SQL concatenation, unescaped output |
| Missing error handling | Happy-path only; no try/catch, no null checks, no timeout handling |
| Redundant abstractions | Unnecessary wrappers, premature generalization, over-engineered patterns |
| Copy-paste drift | Similar blocks with subtle inconsistencies across files |
| Test theater | Tests that assert implementation details, mock everything, or test the framework |
| Accessibility omissions | Missing alt text, broken ARIA, no keyboard handling, div soup |
| Design system violations | Components that ignore existing tokens, spacing, or component patterns |
| Confident but wrong comments | Docstrings that describe what the code should do, not what it actually does |
Sources: Hallucination Detection, AI Design Antipatterns
Severity Rubric
| Priority | Label | Criteria | Review action |
|---|
| P0 | BLOCKER | Data loss, security hole, correctness bug, crashes in prod path | Must fix before merge |
| P1 | REQUIRED | Missing error handling, broken rollback, undefined behavior, SLA violation | Must fix before merge |
| P2 | SUGGESTED | Test gap for non-critical path, minor inefficiency, readability issue | Fix in this PR or tracked issue |
| P3 | OPTIONAL | Style preference, naming taste, future improvement | Author decides; no block |
Mark each finding with its priority and label. Do not lump P0 and P3 findings in the same comment thread.
When Not to Block a Merge
Blocking is a cost: it delays value delivery, encourages batching future changes to avoid another round, and burns reviewer credibility if used on low-stakes disagreements. Do not block on:
- P3-only findings (style, naming taste, a "nicer" abstraction) — leave as non-blocking suggestions and let the author decide.
- A correct approach you would have written differently, with no identified defect or maintainability cost.
- Missing test coverage for genuinely low-risk, low-change-frequency code, when the author explicitly acknowledges the gap and it is tracked.
- Pre-existing issues outside the diff's blast radius — file a follow-up instead of expanding this review's scope.
- Disagreements that are actually about product/requirements, not the code — escalate to the right owner rather than relitigating in review comments.
Do block on P0/P1 findings, missing tests for genuinely risky new behavior, and anything that would be expensive or unsafe to fix after merge (data migrations, public API shape, security boundaries). When in doubt, separate the blocking finding from the optional ones instead of letting one bleed into the other's priority.
Rubber-Stamp Detection
Fast, low-comment reviews are not automatically a problem — well-written, small, low-risk changes should review quickly. Treat these as a warning signal warranting a second look, not proof of bad review:
- Approval on a diff far larger than roughly 200-400 LOC with review duration implausibly short for that size (see
references/large-pr-review-strategies.md and references/code-review-metrics.md for the size/pace data this heuristic is based on).
- "LGTM" with zero substantive comments on a change touching auth, money movement, migrations, or public APIs.
- A team or individual with a defect-escape rate trending up while review turnaround trends down — the speed gain is likely coming from skipped scrutiny.
- Approvals that only restate the PR description back rather than referencing specific lines or behavior.
Use these as coaching signals (spot-check, pair on a review, ask what was actually read), not as a public leaderboard — see references/code-review-metrics.md for how to track this without creating gaming incentives.
Review the Tests, Not Just the Code
A diff with green tests and no test-quality review is only half-reviewed. Apply the same scrutiny to test code as to production code:
- Confirm new/changed behavior actually has a test that would fail without the fix, not just a test that happens to pass alongside it.
- Watch for tests that assert implementation details (mocking everything, checking internal call counts) instead of observable behavior — these pass trivially and catch nothing on refactor.
- Check that error paths and boundaries are tested, not just the happy path.
- Treat a bug fix with no regression test as incomplete, not as a style nit.
Known Traps
- Reviewing from the PR description first and the diff second. Treat descriptions as claims, not evidence.
- Spending most effort on style and almost none on behavioral risk, migration risk, or rollback safety.
- Treating generated files, snapshots, or lockfile churn as noise without checking whether they hide contract or dependency drift.
- Reviewing only changed lines when the bug is in the surrounding invariant, caller expectations, or teardown path.
- Calling out
needs tests generically without naming the missing scenario, boundary, or regression.
- Accepting benchmark, security, or framework claims in the diff comments without live verification when the claim is version-sensitive.
Common Anti-Patterns
- Treating review as approval theater: light comments on naming while correctness and rollout risk remain unexamined.
- Rewriting the author's architecture in review when the real issue is a smaller bug, missing guardrail, or weak contract.
- Conflating preference with defect. Mark taste as optional and reserve blocking comments for correctness, safety, or maintainability risk.
- Collapsing multiple independent issues into one large comment thread instead of separating discrete findings with evidence.
- Using AI review output as authoritative instead of validating each finding against the actual diff and local context.
Default Review Output
Default to:
- a short summary of intent and risk
- findings grouped by
P0 / P1 / P2 / P3
REQUIRED vs OPTIONAL labeling- concrete remediation: minimal diff, test case, or configuration fix
- follow-up questions only when requirements are genuinely unclear
Use assets/core/review-comment-guidelines.md for phrasing and assets/core/review-checklist-judgment.md for final pass judgment. Label comment intent using the Conventional Comments convention (suggestion:, issue:, question:, nitpick:, praise:) so blocking vs. non-blocking intent is unambiguous without relying on tone.
Navigation
Core references:
Templates:
Sources:
- data/sources.json - verified source set with platform status and replacements for retired links
Freshness Protocol
When the user asks for:
- the best or latest code review tool
- current PR automation practices
- GitHub Copilot vs CodeRabbit vs Qodo vs platform-native options
- whether a tool is still relevant
you must:
- Use web search.
- Prefer official docs and release/status pages over vendor comparison blogs.
- Use data/sources.json as the starting source set.
- Treat vendor metrics and case-study performance numbers as directional unless independently verified.
If web access is unavailable, say so and answer from data/sources.json, clearly marking time-sensitive advice as unverified.
Fact-Checking
- Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
- Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
- Prefer primary sources; report source links and dates for volatile information.
- If web access is unavailable, state the limitation and mark guidance as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
