SuperAPI AI Directory

code-review

Coding & development

View repository

Updated 10-16 09:23

About this skill

Perform a dual-axis review of the diff between the user-provided fixed point and HEAD :

  • Standards: does the code conform to the coding standards documented in this repo?
  • Spec: does the code faithfully implement the source issue / spec?

Both axes run asparallel sub-agentsto avoid contaminating each other's context; then this skill aggregates their findings.

The issue tracker should already be provided to you; if docs/agents/issue-tracker.mdis missing, ask the user to run /setup-matt-pocock-skills。

process

1. Determine the fixed point

Anything the user says is the fixed point: commit SHA, branch name, tag,main、HEAD~5 , etc. If the user did not specify one, ask.

Capture the diff command once:git diff <fixed-point>...HEAD(three-dot, so the comparison target is the merge-base). Also use git log <fixed-point>..HEAD --oneline to record the list of commits.

Before continuing, confirm that the fixed point resolves (git rev-parse <fixed-point>) and that the diff is non-empty. A bad ref or an empty diff should fail here, not after entering the two parallel sub-agents.

2. Find the spec source

Look for the source spec in the following order:

  1. Issue references in commit messages (#123、Closes #45、GitLab !67 , etc.), fetched according to the workflow in docs/agents/issue-tracker.md .
  2. A path passed in by the user as an argument.
  3. docs/、specs/ or .scratch/ a spec file matching the branch name or feature.
  4. If nothing is found, ask the user where the spec is. If the user says there is no spec, theSpec sub-agent skips and reports "no spec available".

3. Find the standards source

Anything in the repo that documents how code should be written, e.g. CODING_STANDARDS.md or CONTRIBUTING.md。

Beyond the standards documented by the repo itself, the Standards axis always carries the following smell baseline: a fixed set of Fowler code smells (Refactoring Chapter 3), which apply even if the repo has no conventions at all. There are two rules:

  • The repo overrides. A documented repo standard always takes precedence; if it endorses something the baseline would flag, suppress that smell.
  • Always a judgement call. Each smell is a labeled heuristic (e.g. "possible Feature Envy"), not a hard violation; like the other standards here, skip anything tooling already enforces.

Read each smell according to what it is -> how to fix and check it against the diff:

  • Mysterious Name: the name of a function, variable, or type does not say what it does or holds. -> rename it; if no honest name can be found, the design itself may be murky.
  • Duplicated Code: the same logic shape appears in multiple hunks or files. -> extract the shared shape and have both sides call it.
  • Feature Envy: a method accesses another object's data more than its own data. -> move the method onto the data it envies.
  • Data Clumps: the same groups of fields or params always appear together. -> wrap them into a type to pass around.
  • Primitive Obsession: a primitive or string stands in for a domain concept that deserves its own type. -> give that concept a small type.
  • Repeated Switches: for the same type, the same switch/if cascade is repeated across changes. -> replace it with polymorphism, or share a single map.
  • Shotgun Surgery: one logical change forces the diff to modify many files. -> gather the things that change together into one module.
  • Divergent Change: one file or module is modified for multiple unrelated reasons. -> split it so that each module changes for only one reason.
  • Speculative Generality: add abstraction, params, or hooks for requirements the spec does not have. -> delete it, inline it back, until there is a real need.
  • Message Chains: long chained navigation that the caller should not depend on a.b().c().d(). -> hide this navigation behind a method on the first object.
  • Middle Man: the class or function is basically just continuing to delegate. -> delete it and call the real target directly.
  • Refused Bequest: the subclass or implementer ignores or overrides most of what it inherits. -> remove inheritance and use composition.

4. Launch two sub-agents in parallel

Standards sub-agent prompt includes:

  • the full diff command and commit list.
  • the list of standards-source files found in Step 3,as well as the full text of the smell baseline from Step 3; the sub-agent has no other way to read it.
  • Brief:"Report, per file/hunk where relevant, (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls: documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."

Spec sub-agent prompt includes:

  • The diff command and commit list.
  • The path of the spec or its already-fetched contents.
  • Brief:"Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."

If the spec is missing, skip the Spec sub-agent and explain this in the final report.

5. Summary

Under the ## Standards and ## Spec headings, present the two reports, either verbatim or lightly cleaned up.Do notmerge or reorder the findings; these two axes are deliberately kept separate (see Why two axes)。

Finally, summarize in one line: the total number of findings for each axis, and the most severe issue within each axis (if any). Do not pick a single overall winner across the axes; keeping them separate is meant to avoid this kind of reranking.

Why two axes

A change may pass one of the axes but fail the other:

  • The code complies with all standards, but implements the wrong thing -> Standards pass, Spec fail.
  • The code fully meets the issue requirements, but breaks project conventions -> Spec pass, Standards fail.

Reporting separately prevents one axis from masking the other.