Review
Run a parallel Standards-and-Spec diff review from a fixed git point through HEAD before you merge or ship a branch.
Overview
Review is an agent skill most often used in Ship (also Operate, Build) that runs parallel Standards and Spec diff reviews from a pinned git point to HEAD and reports them side by side.
Install
npx skills add https://github.com/mattpocock/skills --skill reviewWhat is this skill?
- Pins any fixed point (commit, branch, tag, merge-base) and uses three-dot `git diff` plus commit log
- Runs Standards review (repo coding standards) and Spec review (issue/PRD fidelity) in parallel sub-agents
- Aggregates both axes into one side-by-side report without cross-contaminating agent context
- Expects `docs/agents/issue-tracker.md` via `/setup-matt-pocock-skills` when the tracker is missing
- Designed for explicit “review since X”, WIP, and open-PR review requests
- Two review axes: Standards and Spec
- Parallel sub-agents run both axes before aggregation
Adoption & trust: 24.4k installs on skills.sh; 121k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a branch or PR but no structured way to see both standards compliance and spec fidelity in one pass.
Who is it for?
Solo builders merging feature branches who already document standards and track work in issues or PRDs.
Skip if: Repos with no issue tracker or standards docs, or when you only need a quick syntax check without git range context.
When should I use this skill?
User wants to review a branch, PR, work-in-progress changes, or asks to review since a fixed commit, branch, or tag.
What do I get? / Deliverables
You get an aggregated two-axis review report anchored to your chosen fixed point, ready for fixes or merge.
- Side-by-side Standards and Spec findings for git diff fixed-point...HEAD
- Commit list for fixed-point..HEAD
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship/review is the canonical shelf because the skill’s core job is pre-merge quality and requirements fit on a branch or PR. Subphase review matches code-review workflows that compare HEAD to a pin (branch, tag, or commit) rather than one-off debugging.
Where it fits
Compare your feature branch to main before merge with separate standards and spec scores.
Audit everything merged since last release tag for drift from documented conventions.
Validate WIP commits still implement the ticket you linked in the issue tracker.
How it compares
Structured dual-axis branch review with parallel agents—not a single generic “review my code” chat prompt.
Common Questions / FAQ
Who is review for?
Indie and solo developers using agentic git workflows who want Standards and Spec coverage before merge.
When should I use review?
In Ship when reviewing a PR or branch; in Operate when auditing changes since a tag; in Build when validating WIP against an issue before opening a PR.
Is review safe to install?
It drives git diff and log commands and reads repo docs; review the Security Audits panel on this Prism page before enabling in sensitive repos.
SKILL.md
READMESKILL.md - Review
# Review Two-axis review of the diff between `HEAD` and a fixed point the user supplies: - **Standards** — does the code conform to this repo's documented coding standards? - **Spec** — does the code faithfully implement the originating issue / PRD / spec? Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing. ## Process ### 1. Pin the fixed point Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what — a branch, a commit, or `main`?" Don't proceed until you have it. Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`. ### 2. Identify the spec source Look for the originating spec, in this order: 1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`. 2. A path the user passed as an argument. 3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature. 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available". ### 3. Identify the standards sources Anything in the repo that documents how code should be written. Common locations: - `CLAUDE.md`, `AGENTS.md` - `CONTRIBUTING.md` - `CONTEXT.md`, `CONTEXT-MAP.md`, per-context `CONTEXT.md` files - `docs/adr/` (architectural decisions are standards) - `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json` (machine-enforced standards — note them but don't re-check what tooling already checks) - Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md`, or similar at the repo root or under `docs/` Collect the list of files. The **Standards** sub-agent will read them. ### 4. Spawn both sub-agents in parallel Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both. **Standards sub-agent prompt** — include: - The full diff command and commit list. - The list of standards-source files you found in step 3. - The brief: "Read the standards docs. Then read the diff. Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words." **Spec sub-agent prompt** — include: - The diff command and commit list. - The path or fetched contents of the spec. - The brief: "Read the spec. Then read the diff. 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 note this in the final report. ### 5. Aggregate Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate so the user can see them independently. End with a one-line summary: total findings per ax