code-review Skill – Dual-Axis AI Code Review

Skill Overview

The code-review skill performs two separate code reviews of all code changes since a specified fixed point (commit, branch, tag, or merge-base): one along the standards axis and one along the specification axis. The two reviews run independently in parallel subagents and their results are ultimately reported side by side.

Applicable Scenarios

1. Review before merging a branch or PR: Once branch development is complete and it is ready to be merged into main, first confirm that it both follows the repository’s coding standards and actually implements the intended functionality.
2. Review uncommitted workspace changes: When you have a set of changes and are unsure whether they are correct, use a fixed point (such as HEAD~5) to define the review range and have the two review tracks provide independent conclusions.
3. Verifying conformance to requirements: When an issue or specification document is detailed, use this to check item by item what has been implemented, what is only partially implemented, and what has been added without being requested.

Core Features

1. Independent dual-axis review: The standards axis answers, “Does the code comply with the repository’s documented coding standards?” The specification axis answers, “Does the code faithfully implement the original issue or specification?” The two axes are deliberately kept separate and are not re-ranked together, because one dimension can easily obscure the other—code that is fully compliant but solves the wrong problem, or code that solves the right problem while violating project conventions, are both common.
2. Parallel subagent execution: The two review tracks are handled independently by parallel subagents, preventing context contamination. The main process then consolidates the results. The skill first verifies that the fixed point can be resolved and that the diff is non-empty, preventing invalid input from reaching the parallel subagents and failing there.
3. Automatic aggregation of standards sources: The standards axis collects all files in the repository that describe how code should be written (such as CODING_STANDARDS.md and CONTRIBUTING.md), then supplements them with a fixed baseline of code smells (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, and Refused Bequest). Two rules govern this baseline: standards documented by the repository take precedence and may override it; each code smell is only a “suspected” indicator, not a hard violation. Issues that tooling already handles are skipped.
4. Specification source tracing: Original specifications are searched for in the following order: issue references in commit messages (#123, Closes #45, GitLab !67), a path supplied directly by the user, files matching the branch name under docs/, specs/, or .scratch/; only when none of these are found does the tool ask the user.

Frequently Asked Questions

How is the code-review skill different from ordinary AI code review?

Ordinary code review typically answers only, “Is this code well written?” This skill separates the question into two: is it well written (standards), and is it the right thing to write (specification)? Each track produces its own report without cross-ranking, so you can see both “fully compliant but solves the wrong problem” and “solves the right problem but violates project conventions.”

Why are the standards and specifications handled separately instead of being combined into one report?

Because combining them allows one dimension to obscure the other. A combined report can easily place a serious issue such as “the requirement was not implemented” alongside a minor issue such as “the naming is not clear enough,” comparing them in the same list and distorting both results. Reporting them separately, with each axis identifying its most serious issue, is an intentional design choice.

Can it still be used when no matching issue or specification document is found?

Yes, but only half of it will run. Without a specification source, the specification-axis subagent is skipped, and the report explicitly states “No usable specification.” The standards axis continues to run as usual. In addition, if the repository lacks docs/agents/issue-tracker.md, the skill will prompt you to run /setup-matt-pocock-skills first to provide the issue-tracking reading workflow.

Will this skill modify my code?

No. Its output is a review report. It only reads the diff and repository documentation; it does not write code, commit, or push anything. You decide whether and how to make changes.

What needs to be prepared before use?

At minimum, you need a resolvable fixed point (a commit SHA, branch name, tag, main, HEAD~5, and so on). If none is specified, the skill will ask you. The skill will verify that the ref resolves and that the diff against HEAD is non-empty. If either check fails, it will stop before launching the parallel reviews.