code-review

HEAD

• Standards — Does the code comply with the coding standards documented in this repo?
• Spec — Does the code faithfully implement the source issue / PRD / spec?

docs/agents/issue-tracker.md

/setup-matt-pocock-skills

Process

1. Pin the fixed point

main

HEAD~5

git diff <fixed-point>...HEAD

git log <fixed-point>..HEAD --oneline

git rev-parse <fixed-point>

2. Identify the spec source

1. Issue references in commit messages (

   #123

   ,

   Closes #45

   , GitLab

   !67

   , etc.) — retrieve according to the workflow in

   docs/agents/issue-tracker.md

   .
2. Path passed as an argument by the user.
3. PRD/spec files under

   docs/

   ,

   specs/

   or

   .scratch/

   that match 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, the Spec sub-agent skips and reports "no spec available".

3. Identify the standards sources

CODING_STANDARDS.md

CONTRIBUTING.md

• The repo overrides. Documented repo standards always take precedence; if it approves something that would be flagged by the baseline, suppress that smell.
• Always a judgement call. Each smell is a labeled heuristic (e.g., "possible Feature Envy"), not a hard violation; like other standards here, skip items that are already enforced by tooling.

• Mysterious Name — The name of a function, variable, or type does not explain what it does or holds. -> Rename it; if an honest name cannot be found, the design itself may be unclear.
• Duplicated Code — The same logic pattern appears in multiple hunks or files. -> Extract the shared pattern and have both sides call it.
• Feature Envy — A method accesses another object's data more than its own. -> Move the method to the object whose data it envies.
• Data Clumps — The same groups of fields or parameters always appear together. -> Package them into a single type for passing.
• Primitive Obsession — Primitives or strings are used instead of domain concepts that deserve their own type. -> Create a small type for that concept.
• Repeated Switches — The same

  switch

  /

  if

  cascade for the same type is repeated in the changes. -> Replace with polymorphism or share a map.
• Shotgun Surgery — A single logical change requires scattered modifications across many files in the diff. -> Consolidate things that change together into one module.
• Divergent Change — A file or module is modified for multiple unrelated reasons. -> Split it so each module changes for only one reason.
• Speculative Generality — Abstractions, parameters, or hooks are added for requirements not specified. -> Remove it and inline it back until there is a real need.
• Message Chains — Long chained navigation

  a.b().c().d()

  that the caller should not depend on. -> Hide this navigation behind a method in the first object.
• Middle Man — A class or function basically just delegates further. -> Remove it and call the real target directly.
• Refused Bequest — A subclass or implementer ignores or overrides most of the inherited content. -> Remove inheritance and use composition.

4. Spawn both sub-agents in parallel

Agent

general-purpose

• The complete 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 access 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."

• The diff command and commit list.
• The path to the spec or the retrieved content.
• 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."

5. Aggregate

## Standards

## Spec

Why two axes

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