code-review

Code Review

A two-axis review of the diff between a fixed point and the current head:

• Standards — does the code conform to the repo's documented coding standards?
• Spec — does the code faithfully implement the originating issue / spec?

Run both axes as parallel sub-agents so they don't pollute each other's context, then aggregate. This is guidance, not a complete checklist — verify the live base and head before reviewing, and read enough surrounding code to understand the design.

The defining constraint: prioritize correctness, lifecycle, security, and broken required behavior over style. A short review with one substantiated blocker is better than a list of nits.

Why two axes

A change can pass one axis and fail the other:

• Code that follows every standard but implements the wrong thing → Standards pass, Spec fail.
• Code that does exactly what the issue asked but breaks the project's conventions → Spec pass, Standards fail.

Reporting them separately stops one axis from masking the other. Do not merge or rerank findings across axes.

Process

1. Pin the fixed point and the spec source

Capture the diff against the merge-base of the supplied fixed point (commit, branch, tag). Find the originating spec in order: issue references in commit messages → a path the user passed → a spec file under the repo's docs/specs directory. If there is no spec, the Spec axis reports "no spec available" and skips.

2. Identify the standards sources

Anything the repo documents about how code should be written (a CODING_STANDARDS.md, CONTRIBUTING.md, AGENTS.md). On top of that, always carry the smell baseline below, which applies even when the repo documents nothing:

• The repo overrides. A documented repo standard wins; where it endorses something the baseline flags, suppress the smell.
• Always a judgement call. Each smell is a labelled heuristic, never a hard violation; skip anything tooling already enforces.