Conduct a two-axis review of the diff between HEAD and a user-specified fixed point:
- Convention—does the code comply with this repository's documented coding conventions?
- Spec—does the code faithfully implement the original issue / PRD / spec?
The two axes run asparallel sub-agents , without contaminating each other's context, and then this skill aggregates the findings from both sides.
The issue tracker should already be available to you—if docs/agents/issue-tracker.md is missing, run /setup-matt-pocock-skills。
Process
1. Determine the fixed point
Anything the user says can serve as the fixed point—a commit SHA, branch name, tag,main、HEAD~5 , etc. Do not improvise; just pass it through. If the user did not specify one, ask: "What should the review be based on—a branch, a commit, or main?" Do not continue until you get an answer.
Capture the diff command:git diff <fixed-point>...HEAD(three dots, so the comparison is against the merge-base). Also record the commit list via git log <fixed-point>..HEAD --oneline .
Before continuing, confirm that the fixed point resolves (git rev-parse <fixed-point>) and that the diff is non-empty. A bad reference or an empty diff should fail here—it should not be left to two parallel sub-agents to handle.
2. Determine the spec source
Look for the original spec in the following order:
- issue references in the commit message (
#123、Closes #45、GitLab!67, etc.)—fetch them according to the workflow indocs/agents/issue-tracker.md. - a path passed in by the user as an argument.
docs/、specs/or.scratch/a PRD/spec file whose name matches the branch name or feature name.- If nothing is found, ask the user where the spec is. If the user says there is none, thespecsub-agent skips and reports "no spec available".
3. Determine the convention source
Any documented repository content that states how code should be written. Common locations:
CLAUDE.md、AGENTS.mdCONTRIBUTING.mdCONTEXT.md、CONTEXT-MAP.md, theCONTEXT.mdfile for each contextdocs/adr/(architecture decisions are conventions).editorconfig、eslint.config.*、biome.json、prettier.config.*、tsconfig.json(tool-enforced conventions—just document them, do not duplicate checks the tool already performs)- any
docs/at the repository root or underSTYLE.md、STANDARDS.md、STYLEGUIDE.mdor similar files
In addition to what the repository documents, the convention axis always carries the followingsmell baseline—a fixed set of code smells from Chapter 3 of Fowler's Refactoring, applicable even if the repository has no documentation at all. Two binding rules:
- Repository overrides convention. Documented repository standards always take precedence; if the repository explicitly endorses certain baseline judgments, suppress that smell.
- Always a matter of judgment. Each smell is a labeled heuristic ("possible Feature Envy"), never a hard violation — and, like all criteria here, skip what the tooling already enforces.
Each smell is formatted asWhat it is → How to fix; match it against the diff:
- Mysterious Name— the name of a function, variable, or type does not reveal what it does or means. → Rename it; if you cannot find an honest name, the design itself is unclear.
- Duplicated Code— the same logical shape appears in multiple hunks or files in the change. → Extract the shared shape and call it from both places.
- Feature Envy— a method accesses another object's data more than its own. → Move the method onto the data it envies.
- Data Clumps— the same group of fields or parameters repeatedly appears together (a type waiting to be born). → Package them into a type and pass that type.
- Primitive Obsession— using a primitive type or string to represent a concept that deserves its own type. → Give the concept its own small type.
- Repeated Switches— repeatedly using the same
switch/ifcascade for the same type. → Replace it with polymorphism, or use a single map shared by both. - Shotgun Surgery— one logical change forces modifications scattered across many files in the diff. → Gather what changes together into one module.
- Divergent Change— one file or module is modified for multiple unrelated reasons. → Split it so that each module changes for a single reason.
- Speculative Generality— abstractions, parameters, or hooks added for requirements that do not exist in the spec. → Delete them; inline back until a real need appears.
- Message Chains— lengthy
a.b().c().d()navigation that the caller should not depend on. → Hide the traversal behind a method on the first object. - Middle Man— a class or function mostly just delegates to others. → Cut it out and call the real target directly.
- Refused Bequest— a subclass or implementer ignores or overrides most of what it inherits. → Abandon inheritance and use composition instead.
4. Launch two subagents in parallel
Send one message containing two Agent tool calls. Both use the general-purpose subagent.
Spec subagent prompt— include:
- The full diff command and commit list.
- The list of spec source files you found in step 3,plus the smell baseline from step 3(paste it in full — the subagent has no other way to get it).
- Task brief: "Report—listed by file/hunk—(a) every place in the diff that violates a documented convention: cite the convention (file + rule); and (b) any baseline smells you find: name and cite the hunk. Distinguish hard violations from judgment calls—violations of documented conventions can be hard, but baseline smells are always judgment calls, and documented repository standards override the baseline. Skip anything the tooling already enforces. Within 400 words."
Spec sub-agent prompt—includes:
- The diff command and the commit list.
- The path to the spec file or the content retrieved.
- Task brief: "Report: (a) requirements the spec requires but that are missing or incomplete; (b) behavior present in the diff but not required by the spec (scope creep); (c) requirements that appear implemented but whose implementation may be wrong. Cite the spec text for each item. Within 400 words."
If the spec is missing, skip the spec sub-agent and note this in the final report.
5. Aggregate
Under the ## 规范 and ## 规格 headings, present the two reports, either verbatim or lightly tidied.Do notmerge or reorder the findings—the two axes are deliberately kept separate (see "Why two axes").
End with a one-line summary: the total number of findings on each axis, and the single most severe issue within each axis, if any. Do not pick one overall winner across the axes—that is exactly the reordering the split is meant to prevent.
Why two axes
A change can pass review on one axis but not the other:
- The code follows every convention but implements the wrong feature → convention passes, spec fails.
- The code implements exactly what the issue asks for but violates project conventions → spec passes, convention fails.
Reporting them separately prevents one axis from masking the other.