Code Review: Standards and Spec

What it does

This review workflow starts by resolving a commit, branch or tag and checking that the merge-base diff contains changes. It locates the originating issue or specification and the repository’s documented standards before assigning independent review contexts. Its standards axis includes explicitly labelled code-smell heuristics, with repository rules taking precedence. The specification axis looks for missing behavior, wrong implementations and added scope. Findings stay separate in the final report; the skill does not combine them into an overall score.

When to use it

• A feature branch passes linting but may omit an acceptance criterion.
• A pull request implements the requested behavior while introducing avoidable coupling.
• A team wants a repeatable review against a known release tag or merge-base.

Step-by-step workflow

1. Resolve the requested comparison reference and confirm that the three-dot diff is non-empty.
2. Locate the originating issue or specification; explicitly mark the spec axis unavailable if none exists.
3. Read the project standards, contribution rules and the skill’s smell baseline.
4. Run fresh, independent Standards and Spec review contexts over the same fixed diff.
5. Present the two reports separately, with evidence, counts and the worst finding within each axis.

Example request

Use code-review against origin/main for our invoice-export branch. The originating requirement is docs/invoice-export-spec.md. Check CONTRIBUTING.md and our coding standards. Keep standards findings separate from missing or incorrect acceptance criteria. Cite the relevant rule or requirement and changed code for every actionable finding. Skip issues already enforced by tooling. Do not edit files, commit, post review comments or merge the branch.

Worked example

Suppose the spec requires UTF-8 CSV output and cancellation of an export, while the branch only implements CSV generation. A clean implementation can pass the Standards axis but fail Spec for missing cancellation. Conversely, a complete feature can still violate a documented error-handling rule. The useful output preserves both conclusions, references the relevant hunks and avoids disguising a requirement gap with a positive style assessment. This is an illustrative review scenario, not a review executed for this directory.

What you get

Two evidence-backed review reports with distinct standards and specification findings; a missing-spec statement where appropriate.

How to evaluate the result

• Verify the comparison reference resolves and includes the intended changes.
• Confirm each hard standards finding cites an actual repository rule.
• Check that missing requirements remain visible separately from style concerns.

What you need

Git history, a resolvable comparison reference, repository standards and access to the originating spec or issue. Full behavior requires parallel subagent support.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

The workflow is a review, not proof of correctness or a replacement for tests. Code smells are judgement calls rather than automatic violations. Without a spec, requirement coverage cannot be established. Tracker access and subagent capabilities depend on the host.

Related workflows

• Use diagnosing-bugs when a review finding needs a reproducible failure.
• Use to-spec before review when requirements have not been recorded.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license