Code Review
Purpose
Evaluate a change for correctness, readability, maintainability, and consistency with the project's conventions and architecture — and report actionable findings. Supports Gate 6.
When to Use
- After implementation of a task/feature/fix, before merge/release.
- For a code review request type.
- Not as a substitute for security review (
security-review) or tests (testing-strategy).
Inputs
- The diff/change under review and its context (work item, acceptance criteria).
- Project conventions and architecture.
Discovery Questions
- What was this change supposed to do (acceptance criteria)?
- Which files/modules changed, and what do they touch?
- Are there tests, and do they cover the change?
Responsibilities
- Verify the change meets its acceptance criteria.
- Check correctness (logic, edge cases, error handling).
- Check clarity/maintainability (naming, structure, duplication).
- Check convention/architecture fit and unintended behavior changes.
- Confirm tests exist and are meaningful (delegate depth to
testing-strategy).
- Report findings with severity and confirmed vs suggestion.
Required Workflow
- Read acceptance criteria + the diff.
- Assess correctness and edge cases.
- Assess clarity, maintainability, conventions.
- Check tests cover the change.
- Flag security/perf concerns to the specialist skills.
- Report findings (severity, confirmed/suggestion) with
file:line.
- On a tracked project, record them via
project-management: confirmed defects through bug intake, accepted suggestions as TECH- tasks (../../system/PROJECT_MANAGEMENT_RULES.md, recording work).
Decision Rules
- Block on confirmed correctness or security defects; suggestions don't block.
- Prefer the smallest correct change; flag scope creep.
- Hand security-specific and performance-specific concerns to
security-review / performance-review.
Rules
- Be specific: cite
file:line and the failure scenario.
- Separate confirmed defects from style/preference.
- Don't approve unverified correctness; don't rubber-stamp.
Anti-Patterns
- Vague feedback with no location or scenario.
- Bikeshedding style while missing correctness.
- Approving without checking the change meets its criteria.
Validation Checklist
Definition of Done
A review report with located, severity-rated findings (confirmed defects vs suggestions), a clear pass/block verdict against acceptance criteria, and any security/perf items routed to specialists.
Related Skills
security-review, performance-review, testing-strategy, ai-output-review, final-quality-audit, project-orchestrator, project-management.
Related Knowledge
../../knowledge/ (conventions, architecture).
Related References
../../references/<topic>/ for the language/framework idioms if needed.
Context Loading Guidance
- Requires: the diff, acceptance criteria, relevant conventions.
- Does not require: the whole repo, unrelated references, planning skills.
- May load:
security-review, performance-review, testing-strategy for depth.
- Stop when: the review report is delivered.
Token Efficiency Guidance
Review the diff plus only the surrounding context needed to judge it. Don't re-read the whole module unless the change's correctness depends on it.
1---2name: code-review3description: Use to review a change or diff for correctness, clarity, maintainability, and convention-fit before it advances. Reports findings with severity, separating confirmed defects from suggestions; does not rubber-stamp.4metadata:5 source: https://skillmd.com/skills/ahtishamshahzad/code-review6---78# Code Review910## Purpose1112Evaluate a change for correctness, readability, maintainability, and consistency with the project's conventions and architecture — and report actionable findings. Supports Gate 6.1314## When to Use1516- After implementation of a task/feature/fix, before merge/release.17- For a **code review** request type.18- **Not** as a substitute for security review (`security-review`) or tests (`testing-strategy`).1920## Inputs2122- The diff/change under review and its context (work item, acceptance criteria).23- Project conventions and architecture.2425## Discovery Questions2627- What was this change supposed to do (acceptance criteria)?28- Which files/modules changed, and what do they touch?29- Are there tests, and do they cover the change?3031## Responsibilities3233- Verify the change **meets its acceptance criteria**.34- Check **correctness** (logic, edge cases, error handling).35- Check **clarity/maintainability** (naming, structure, duplication).36- Check **convention/architecture fit** and unintended behavior changes.37- Confirm **tests** exist and are meaningful (delegate depth to `testing-strategy`).38- Report findings with **severity** and **confirmed vs suggestion**.3940## Required Workflow41421. Read acceptance criteria + the diff.432. Assess correctness and edge cases.443. Assess clarity, maintainability, conventions.454. Check tests cover the change.465. Flag security/perf concerns to the specialist skills.476. Report findings (severity, confirmed/suggestion) with `file:line`.487. On a tracked project, record them via `project-management`: confirmed defects through bug intake, accepted suggestions as `TECH-` tasks (`../../system/PROJECT_MANAGEMENT_RULES.md`, recording work).4950## Decision Rules5152- Block on confirmed correctness or security defects; suggestions don't block.53- Prefer the smallest correct change; flag scope creep.54- Hand security-specific and performance-specific concerns to `security-review` / `performance-review`.5556## Rules5758- Be specific: cite `file:line` and the failure scenario.59- Separate confirmed defects from style/preference.60- Don't approve unverified correctness; don't rubber-stamp.6162## Anti-Patterns6364- Vague feedback with no location or scenario.65- Bikeshedding style while missing correctness.66- Approving without checking the change meets its criteria.6768## Validation Checklist6970- [ ] Change meets acceptance criteria.71- [ ] Correctness/edge cases assessed.72- [ ] Clarity/maintainability assessed.73- [ ] Conventions/architecture respected.74- [ ] Tests cover the change.75- [ ] Findings have severity + confirmed/suggestion + location.7677## Definition of Done7879A review report with located, severity-rated findings (confirmed defects vs suggestions), a clear pass/block verdict against acceptance criteria, and any security/perf items routed to specialists.8081## Related Skills8283`security-review`, `performance-review`, `testing-strategy`, `ai-output-review`, `final-quality-audit`, `project-orchestrator`, `project-management`.8485## Related Knowledge8687`../../knowledge/` (conventions, architecture).8889## Related References9091`../../references/<topic>/` for the language/framework idioms if needed.9293## Context Loading Guidance9495- **Requires:** the diff, acceptance criteria, relevant conventions.96- **Does not require:** the whole repo, unrelated references, planning skills.97- **May load:** `security-review`, `performance-review`, `testing-strategy` for depth.98- **Stop when:** the review report is delivered.99100## Token Efficiency Guidance101102Review the diff plus only the surrounding context needed to judge it. Don't re-read the whole module unless the change's correctness depends on it.