Skip to content
AI Prompts Logo AI Prompts & Skills

code-review

Code Review

Section titled “Code Review”

Purpose

Section titled “Purpose”

This skill performs a structured, project-aware code review. It evaluates changes against the project’s existing conventions, the requirements that motivated the change, and general software quality principles — producing actionable, severity-tiered feedback rather than a wall of comments.

If the change originated from a plans/<name>/tasks.md task, the review also validates that the implementation satisfies the task’s acceptance criteria, traces back to the correct PRD requirements, and conforms to the plan’s design.md and ADRs when they exist.

In the development lifecycle, this skill is the quality step of the build pipeline — run it per task or per phase during tasks-to-code, and always before release-checklist (which hard-blocks on unresolved 🔴 Blocking findings in review.md).

Inputs

Section titled “Inputs”

The skill accepts any of the following:

  • A diff — pasted or referenced (e.g., git diff main...feature-branch)
  • A list of changed files — “review the changes in src/auth/ and tests/auth.test.ts”
  • A branch or PR description — with enough context to identify what changed and why
  • A task reference — “review the implementation of task 2.3” (reads plans/<name>/tasks.md for acceptance criteria)

If the scope is unclear, ask before reviewing. A review without clear scope produces noise, not signal.

Workflow

Section titled “Workflow”

Phase 1: Understand the Change

Section titled “Phase 1: Understand the Change”

Before reading any code, understand why the change exists.

  1. Identify the motivation — Is this from a PRD task? A bug fix? A refactor? An unplanned change?

    • If from a task: read plans/<name>/tasks.md to get the task’s acceptance criteria and plans/<name>/prd.md for the underlying requirements — and plans/<name>/design.md plus plans/<name>/adr/ when they exist, because the change must also conform to the architecture
    • If a bug fix: ask for the bug report or reproduction steps
    • If neither: ask the user what this change is intended to do

  2. Identify the blast radius — What does this change touch? How many files? What systems are affected?

  3. Identify the risk profile — Is this security-sensitive? Does it touch auth, data persistence, payments, or user-facing content? Higher-risk changes require more thorough review.

Phase 2: Codebase Discovery

Section titled “Phase 2: Codebase Discovery”

Run targeted discovery to understand the project’s conventions in the areas the change touches. See ../idea-to-prd/references/codebase-discovery.md for the full checklist. Focus on:

  • Patterns in the changed area — How does the surrounding code handle similar concerns?
  • Test conventions — Where do tests live? What testing patterns are expected?
  • Quality gates — Which lint, format, type-check, and test commands must pass?
  • Error handling patterns — What is the project’s standard approach?

This step transforms the review from “generic advice” to “specific to how this project works.”

Phase 3: Review

Section titled “Phase 3: Review”

Evaluate the change across the dimensions in references/review-checklist.md. Key dimensions:

  1. Correctness — Does the code do what it claims? Are edge cases handled? Are there off-by-one errors, null dereferences, race conditions?
  2. Requirements alignment — If from a task: does it satisfy every acceptance criterion? If from a PRD: does it implement all stated requirements and nothing outside them?
    • Design conformance — when the plan has a design.md: does the change respect the component boundaries, API/data contracts, and ADR decisions the design defines? An undeclared deviation from the design is a 🔴 Blocking finding — the fix is either to conform, or to route the conflict through prd-to-design’s design-change protocol so the design is revised deliberately. Check decisions.md first: a deviation already recorded and justified there is a decision, not a finding.
  3. Security — Are inputs validated? Are secrets handled correctly? Are authorization checks in place? See references/review-checklist.md for the security checklist. This covers the security of this change; for a dedicated whole-system threat model — asset/boundary inventory, object-level authz, dependency CVEs, security logging, rate limiting — use the security-review skill.
  4. Test coverage — Are there tests? Do they cover the happy path, error cases, and edge cases? Are they testing behavior or implementation details?
  5. Consistency — Does this follow the project’s error handling, naming, file organization, and import patterns?
  6. Performance — Are there obvious N+1 queries, missing indexes, unbounded loops, or synchronous operations that should be async?
  7. Maintainability — Is the code readable? Are abstractions at the right level? Is anything overly clever?

Phase 4: Produce Feedback

Section titled “Phase 4: Produce Feedback”

Structure all findings using the format in references/feedback-format.md. Every finding carries a severity from the single shared severity scale. Code review applies it using disposition names — 🔴 Blocking (Critical), 🟡 Suggestion (Major), ⚪ Nit (Minor) — plus ✅ Praise, a positive callout that is not a severity. See references/feedback-format.md for calibration and when to use each.

Present findings grouped by file, then by severity within each file. Always lead with a summary.

Phase 5: Track (Optional)

Section titled “Phase 5: Track (Optional)”

If the change has findings that require follow-up, offer to produce a plans/<name>/review.md tracking document. This is recommended when:

  • There are multiple blocking findings
  • Suggestions should be tracked across rounds of revision
  • The review is part of a formal PR process

The review.md format is defined in references/feedback-format.md.

review.md is not just a log — it is a release gate: release-checklist hard-blocks on any 🔴 Blocking finding not marked resolved. Keep it current across rounds so the gate reflects reality.

When a plan is active, file the review’s “Future Opportunities” (worthwhile improvements beyond this change’s scope) into plans/<name>/decisions.md under Future Opportunities rather than only mentioning them in the review summary — that is the list refactor executes from, so an opportunity recorded there survives; one only mentioned in passing is lost.

Handling Re-Reviews

Section titled “Handling Re-Reviews”

When the user asks to “re-review” or “check the updates”:

  1. Read the original review findings (from memory or review.md if it was saved)
  2. Check each blocking and suggestion finding against the updated code
  3. Mark resolved items explicitly
  4. Surface any new findings introduced by the revisions
  5. When all blocking items are resolved, confirm the change is ready

Key Principles

Section titled “Key Principles”

Be specific, not prescriptive. Point to the problem and explain why it matters. Do not rewrite the user’s code unless asked. Offer a concrete example only when it makes the feedback clearer.

Distinguish must-fix from should-fix. Every finding being “blocking” is useless signal. Reserve blocking severity for correctness bugs, security issues, and unmet requirements.

Check against the project’s standard. A “violation” is only a violation if the project actually does things differently. Do not flag code that differs from your generic preferences but is consistent with the project’s own patterns.

Acknowledge what’s good. A review that only finds fault misses the opportunity to reinforce correct patterns. ✅ Praise findings are not filler — they signal what to do more of.

No gold-plating in reviews. Do not suggest improvements that go beyond the stated purpose of the change. File them as “Future Opportunities” — in plans/<name>/decisions.md when a plan is active, so refactor can execute them later — rather than feedback on this change.

References

Section titled “References”