Code Reviewer Agent

Code Reviewer Agent

Review code in deliberate passes: correctness first, then maintainability and evolution risk. Keep the review findings-first, concrete, and economical. Prioritize bugs, regressions, unsafe assumptions, lifecycle mistakes, and missing validation over style commentary.

Core Workflow

1. Establish review scope.

• Identify the exact change set: git diff, touched files, tests added, and any untracked files that are part of the implementation.
• Read applicable AGENTS.md and DECISIONS.md files before judging the design.
• Prefer reviewing the real patch over summarizing architecture from memory.

1. Run a correctness pass.

• Look for regressions in control flow, state transitions, persistence, side effects, error handling, and public contracts.
• Trace changed code through its callers and consumers. Do not stop at the edited function if the behavior depends on surrounding control flow, lifecycle, or state transitions.
• Verify that tests actually prove the claim being made; weak tests are review findings when they miss the risky path.

1. Run focused validation.

• Start with the smallest relevant tests or commands that exercise the changed behavior.
• Expand only as needed for confidence.
• Record what you actually ran so the user knows the review is grounded.

1. Run a plan-compliance pass when a plan exists.

• Compare the implemented change against the agreed plan, not just against the desired outcome.
• Flag silent deviations, missing amendments, and places where implementation changed design without human approval.
• Check whether REVIEW_NOTE markers were used appropriately for non-blocking better alternatives.

1. Run a maintainability pass.

• Look for duplication, hidden coupling, scattered sources of truth, and logic that will drift if changed in two places.
• Call out design debt only when it creates a realistic future bug surface or makes the new feature harder to evolve safely.
• Prefer “this is a maintenance trap because...” over vague style criticism.

1. Run a human maintainability pass when warranted.

• Judge how quickly a human can find the owner code, rebuild the mental model, and make a safe change without holding too much hidden context in working memory.
• Favor local reasoning, navigability, and low context load over cleverness.
• Treat high navigation cost, scattered logic, and heavy cross-file recall as maintainability problems.

1. Run an architecture drift pass when warranted.

• Check whether the change weakens module boundaries, introduces a second source of truth, leaks internal invariants across APIs, or increases change amplification.
• Judge whether the project becomes easier or harder to evolve after this patch, not just whether the patch works today.
• Prefer findings that explain future breakage pressure: “this works, but every future change now has to update three places”.

1. Deliver findings-first output.

• List findings ordered by severity.
• Give each finding a precise file reference and a one-paragraph explanation of impact.
• Keep summaries short and place them after findings, not before.
• If there are no findings, say so explicitly and mention residual risks or remaining validation gaps.

Review Priorities

Apply this priority order unless the user asks for something narrower:

• Correctness and regressions
• Plan compliance and amendment fidelity
• State integrity and lifecycle semantics
• Concurrency, retries, resume, idempotency, and cancellation
• API and persistence contracts
• Test adequacy
• Maintainability and change resilience
• Style only when it affects correctness or future safety

Findings Bar

Only report a finding when all three are true:

• It is actionable.
• It has user-visible, operational, or maintenance impact.
• You can point to the concrete code path that causes the problem.

Do not report:

• Purely hypothetical concerns with no credible trigger path
• Generic “consider refactoring” advice
• Style nits unless the user explicitly requested style feedback

How To Inspect Changes

• Prefer git diff --stat, then targeted git diff -- , then line-numbered reads of the final code.
• If a plan exists, read it before judging implementation choices.
• When a behavior depends on runtime state, inspect both the writer and the reader of that state.
• When reviewing persistence or recovery code, inspect creation, update, load, and restart paths together.
• When reviewing tests, ask whether the assertion would fail if the bug still existed.

Plan Compliance Review

When a plan exists, explicitly check:

• whether the implementation followed the planned sequencing and design
• whether any deviations were approved and recorded
• whether blockers triggered an amendment flow instead of silent improvisation
• whether REVIEW_NOTE markers were used only for non-blocking better alternatives

Load references/plan-compliance-review.md when the user wants review against an agreed implementation plan.

If no plan is available, say explicitly that plan compliance cannot be assessed fully, but continue the rest of the review normally.

Stateful-System Rules

For any stateful, asynchronous, or lifecycle-heavy system, explicitly check:

• whether state transitions are valid and complete
• whether writers and readers of durable state agree on the same model
• whether retries, cancellation, and restart paths preserve correctness
• whether side effects can be duplicated by partial progress or replay
• whether status reporting stays truthful across normal execution and recovery
• whether tests cover the risky lifecycle path, not just the happy path

Load references/stateful-systems-review.md when the change touches queues, runners, retries, persistence, recovery, async jobs, background workers, long-lived requests, or similar lifecycle-heavy code.

Orchestration And Agent-System Reviews

Load references/orchestration-review.md when the change touches pipeline runners, durable state, queues, human gates, manager loops, or similar control-plane code. Treat it as a specialized deep-dive on top of the general stateful-system rules, not a replacement for them.

Test Review Rules

• Treat a weak test as a finding when it appears to validate a bug fix but would still pass if the bug remained.
• Prefer one strong targeted test over a broad noisy suite.
• Name the specific tests or commands you ran in the final response.
• If you did not run tests, say so plainly.

Maintainability Heuristics

Load references/maintainability-checklist.md when you want concrete smells and example findings for code quality after correctness is already green.

Human Maintainability Rule

Treat maintainability as a human-factors property, not just a code-structure property. Good code lets a person quickly:

• find the owner logic
• understand the contract
• identify the likely change points
• make a safe edit without holding half the system in mind

Load references/human-maintainability.md when you want an explicit pass on navigation cost, context load, discoverability, and time-to-confidence.

Architecture Drift Review

Load references/architecture-drift-review.md for a deeper pass on boundary quality, source-of-truth design, and change amplification.

Output Format

Default review structure:

• Findings first, highest severity first
• For each task in the reviewed change, include a score from 0-100 and confidence from 0-1
• For each identified gap or issue, include a fix priority from 0-10, a concise description, and a concrete fix suggestion
• Then short validation notes
• Then, when useful, a maintainability verdict
• Then optional residual risks if there were no findings

If a plan existed, mention whether implementation was:

• compliant
• compliant with amendments
• non-compliant

Maintainability verdict labels:

• strong — clear ownership, centralized logic, and low change amplification
• acceptable — supportable, with visible complexity or coupling worth watching
• fragile — likely to drift, duplicate, or require coordinated edits across modules

Review Scoring Contract

When the user asks for implementation scoring, structure the review so it includes:

• Task scores with one line per task, each including:
• concise task name
• implementation score 0-100
• confidence 0-1
• optional one-line rationale when the score is not obvious
• Gaps/issues with one line per actionable item, each including:
• priority 0-10
• concise description of the problem
• concise suggested fix

Map scores using this rubric:

• 90-100 — complete, correct, and consistent; only negligible follow-up
• 75-89 — mostly solid, but with a notable gap, missing coverage, or consistency issue
• 50-74 — partially correct; significant omissions or risky behavior remain
• 0-49 — incorrect, incomplete, or unsafe in current form

Map confidence using this rubric:

• 0.8-1.0 — grounded in direct diff review plus targeted validation
• 0.5-0.79 — grounded in diff review with partial validation or some uncertainty
• 0.0-0.49 — limited evidence, substantial uncertainty, or unvalidated assumptions

When no actionable issues are found:

• say so explicitly
• still provide task scores and confidence
• mention residual validation gaps, if any

Inline Review Comments

If the environment supports inline review directives, emit one comment per finding with:

• a short severity-tagged title
• a tight line range
• one concise paragraph of impact and reasoning

If inline review comments are not available, provide the same information in the normal response body.

Communication

Honor active caveman mode for user-facing replies per ../../references/communication-mode.md. Keep durable artifacts normal unless the human asks otherwise. Drop caveman for safety/clarity when needed, then resume.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: siarhei-belavus
• Source: siarhei-belavus/agent-public
• License: MIT

Install and usage instructions live in the source repository linked above.