<!-- markdownlint-disable MD013 -->
Code Review
Three-axis review of the diff between
and a fixed point the user
supplies:
- Standards — does the code conform to this repo's documented coding
standards?
- Spec — does the code faithfully implement the originating issue / PRD /
spec?
A third, lighter axis applies when the change is non-trivial: Stability —
does the diff ship the property-based tests named in the spec? The Spec agent
additionally verifies that each named invariant/property test exists and fails
loud on a broken invariant, not just example coverage.
Both axes run as
parallel sub-agents (
) so they don't pollute
each other's context; this skill aggregates their findings side by side. The
issue tracker comes from
docs/agents/issue-tracker.md
.
Process
1. Pin the fixed point
Whatever the user said — a commit SHA, bookmark, tag,
,
. If
unspecified, ask. Capture once (prefer
, fall back to
):
/
(three-dot, merge-base), and
/
git log <fixed>..HEAD --oneline
. Confirm the ref
resolves (
/
) and the diff is non-empty before
spawning sub-agents — a bad ref or empty diff fails here, not inside two
children.
2. Identify the spec source
In order: issue references in commit messages (
,
) fetched per
docs/agents/issue-tracker.md
; a path the user passed; a spec under
,
, or
matching the branch. If none, ask; if the user says
there isn't one, the Spec sub-agent reports "no spec available".
3. Identify the standards sources
,
,
,
, etc. On
top of whatever the repo documents, the Standards axis always carries a
smell
baseline — Fowler's code smells (long method, large class, feature envy,
primitive obsession, shotgun surgery, ...) — so review has teeth even when the
repo documents nothing.
4. Run both axes in parallel
Spawn two sub-agents with
:
- Standards agent — the diff + the standards sources + smell baseline.
- Spec agent — the diff + the spec. Reports each user story / acceptance
criterion as met / partial / missing.
5. Aggregate
Report the two axes side by side. Per finding: location (
), the
issue, and the fix. End with a verdict per axis (pass / changes requested) and
the single most important change.
Boundaries
This review is the agent's
pre-flight; the gating approving review is human.
After it passes, hand the PR to a human (label
) — never treat
this review as the merge gate. Reviews; does not apply fixes. The
over-engineering pass is folded into the workflow as the minimalism
over-engineering audit (see
—
/
/
/
/
tags, ending in
); run it from
before this review. For
deeper correctness/security, escalate to a dedicated review pass.