Skip to content
Skills Library
Programming · Review & audit

code-review

/code-review

Review the changes since a fixed point (commit, branch, tag, or merge-base) along three axes: Standards (does the diff follow this repo's documented coding standards?), Spec (does it implement what the originating issue/spec asked for?), and Adversarial Bugs (null paths, races, off-by-one, error handling, security). Each axis runs in a fresh, isolated headless pi sub-process and findings are reported side by side, never merged. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to 'review since X'.

Repository
pi-tools ↗
Licence
Apache-2.0
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/run-axis.sh

What it does and when to use it

Review the changes since a fixed point (commit, branch, tag, or merge-base) along three axes: Standards (does the diff follow this repo's documented coding standards?), Spec (does it implement what the originating issue/spec asked for?), and Adversarial Bugs (null paths, races, off-by-one, error handling, security). Each axis runs in a fresh, isolated headless pi sub-process and findings are reported side by side, never merged. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to 'review since X'.

Triggers from the description

review since X
Original author description

Review the changes since a fixed point (commit, branch, tag, or merge-base) along three axes: Standards (does the diff follow this repo's documented coding standards?), Spec (does it implement what the originating issue/spec asked for?), and Adversarial Bugs (null paths, races, off-by-one, error handling, security). Each axis runs in a fresh, isolated headless pi sub-process and findings are reported side by side, never merged. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to 'review since X'.

How it works

  1. Process
Original SKILL.md headings · 89 lines, 858 words
SKILL.md preview
---
name: code-review
description: "Review the changes since a fixed point (commit, branch, tag, or merge-base) along three axes: Standards (does the diff follow this repo's documented coding standards?), Spec (does it implement what the originating issue/spec asked for?), and Adversarial Bugs (null paths, races, off-by-one, error handling, security). Each axis runs in a fresh, isolated headless pi sub-process and findings are reported side by side, never merged. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to 'review since X'."
---

Three-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 / spec?
- **Adversarial Bugs**: hunt concrete defects — null/undefined paths, off-by-one, races, unhandled errors, resource leaks, injection, broken edge cases.

Each axis runs as a **separate headless pi process** with a fresh context window, so axes never pollute each other — and so the review never happens inside the session that wrote the code. ("Same context reviewing itself isn't review, it's confirmation bias with a slash command.") This skill aggregates their reports.

Design lineage: the two-axis Standards/Spec split and the smell baseline follow Matt Pocock's `code-review` skill (MIT); the adversarial-bug axis and the tooling-first pre-pass follow Geoff Huntley's position that review is an engineering gate, not a prose ritual.

## Process

### 1. Pin the fixed point

The fixed point is whatever the user supplied (commit SHA, branch, tag, `main`, `HEAD~5`). If they didn't supply one, ask — do not guess.

Validate **before** spawning anything:

```sh
git rev-parse --verify <fixed-point>
git diff <fixed-point>...HEAD --stat
```

Three-dot diff: comparison is against the merge-base. Note that staged and uncommitted work is **invisible** to this review — if the user wants that reviewed, tell them to commit first. A bad ref or an empty diff fails here, in front of the user, not inside three sub-processes.

### 2. Tooling pre-pass (Huntley layer)

If it can be checked by a machine, it must not become an LLM finding. Detect and run what the repo has:

- Lint / typecheck / build (`package.json` scripts, `Makefile`, `Cargo.toml`, etc.)
- The test suite, if it's fast enough to be practical.

Record the results verbatim. Pass a summary to every axis brief with the standing instruction: **skip anything tooling already enforces.** If the build, typecheck, or tests fail, say so prominently in the final report — a failing gate usually outranks every prose finding.

### 3. Identify the standards sources

Search the repo for every file documenting how code should be written: `CODING_STANDARDS.md`, `CONTRIBUTING.md`, `AGENTS.md`, `docs/` style guides. When such files exist they are the primary source and **the repo overrides the baseline**.

Regardless, the Standards axis carries the smell baseline in `references/smell-baseline.md` (Fowler, _Refactoring_ ch.3): labelled heuristics ("possible Feature Envy"), never hard violations.

### 4. Identify the spec source

In order:

1. Issue references in commit messages (`#123`, `Closes #45`, `!67`) — fetch via `gh`/`glab` if available.
2. A path the user passed as an argument.
3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch or feature.
4. Ask the user. If there is no spec, **skip the Spec axis** and report "no spec available" — never infer requirements from the code.

### 5. Spawn the three axes in parallel

For each axis, fill its brief template from `references/` and run `scripts/run-axis.sh` (paths relative to this skill directory):

```sh
scripts/run-axis.sh <fixed-point> <filled-brief-file> <output-file>
```

Run all three with a single bash invocation using `&` and `wait`, writing to `.scratch/code-review/<axis>.md` (create the dir). Fill each template's `{{PLACEHOLDERS}}` before launching:

- `references/standards-brief.md` — `{{STANDARDS_SOURCES}}` (file list), `{{SMELL_BASELINE}}` (paste `references/smell-baseline.md` in full), `{{TOOLING_RESULTS}}`.
- `references/spec-brief.md` — `{{SPEC}}` (path or fetched contents), `{{TOOLING_RESULTS}}`.
- `references/adversarial-brief.md` — `{{TOOLING_RESULTS}}`.

`run-axis.sh` captures the diff and commit list itself, launches `pi -p` with `--no-session --no-skills --no-extensions --no-mcp`, and restricts tools to `read,bash`. Sub-agents therefore **cannot** rediscover this skill or load other project machinery — this is the harness-level guard against recursive fan-out. Set `PI_REVIEW_MODEL` to override the model used by axis processes (a cheaper model is often fine; match the model to the task, not to your ego).

Skip the Spec axis if no spec exists. If an axis process fails, report its failure in place of its findings — never silently drop an axis.

### 6. Aggregate — do not blend

Present the reports under `## Standards`, `## Spec`, and `## Adversarial Bugs` headings, verbatim or lightly cleaned. **Never merge, deduplicate across, or re-rank the axes** — a change can pass one axis and fail another, and a blended verdict lets the passing axis hide the failing one.

Close with:

- The tooling pre-pass verdict (build/lint/tests).
- One line per axis: finding count and the worst issue **within that axis** (if any). Never pick a single overall winner.
- This footer, verbatim:

> Findings are hypotheses, not evidence. Every finding carries a citation — verify the citation before acting on it. This review has no convergence guarantee: fix the cited findings and stop. Do not re-run it in a loop waiting for a clean pass, because it never comes.

### 7. Convert repeat findings into enforcement

When a finding names a mistake class the repo will make again, offer to encode it instead of flagging it forever:

- A pre-commit hook, lint rule, or type-level constraint when the check is mechanical.
- A new rule in `CODING_STANDARDS.md` (or equivalent) when it needs judgement — the Standards axis reads that file next run.

Never give the same review feedback three times. The first time you flag it, the second time you automate it.
Files in this package (6)
  • SKILL.md 6 KB
  • references/adversarial-brief.md 2 KB
  • references/smell-baseline.md 2 KB
  • references/spec-brief.md 1 KB
  • references/standards-brief.md 1 KB
  • scripts/run-axis.sh 1 KB

Versions

RepositoryScoreLicence
This page · comalice/pi-tools100Apache-2.0
microsoft/aspire100MIT
kdlbs/kandev100AGPL-3.0
dotnet/runtime100MIT
drosam/agents100MIT
ggml-org/llama.cpp100MIT
ShamelesAbyss/Nyx100Apache-2.0
dzhng/jevgrep100MIT
iuliandita/skills100MIT

Database snapshot: 13.11.2026 · package version 194a83a8487c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90two-axis-code-review
    Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel…
  • 90review-code
    Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating spec/PRD asked for?). Use when the user wants to review a…
  • 90review
    Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel…
  • 90review
    Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel…
  • 90review-changes
    Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the plan, ticket or spec asked for?). Runs both reviews in parallel sub-agents…
  • 90jidoka-code-review
    Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.