Skip to content
Skills Library
Programming · Review & audit

code-review

/code-review

Use when reviewing a change before commit, merge or milestone sign-off — a working copy, a commit, a branch range or a PR. Produces a coverage ledger (every changed file reviewed or skipped with a reason) and severity-ranked, line-anchored findings, each re-checked before it is reported.

Repository
skills ↗
Licence
MIT
Last repository change
13.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
10
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when reviewing a change before commit, merge or milestone sign-off — a working copy, a commit, a branch range or a PR. Produces a coverage ledger (every changed file reviewed or skipped with a reason) and severity-ranked, line-anchored findings, each re-checked before it is reported.

Original author description

Use when reviewing a change before commit, merge or milestone sign-off — a working copy, a commit, a branch range or a PR. Produces a coverage ledger (every changed file reviewed or skipped with a reason) and severity-ranked, line-anchored findings, each re-checked before it is reported.

How it works

  1. Step 1 — Fix the range
  2. Step 2 — Build the ledger (before reading any diff)
  3. Step 3 — Attach rules to each file
  4. Step 4 — Review
  5. Step 5 — Re-check every finding before it is reported
  6. Step 6 — Report
  7. Step 7 — After the review
Original SKILL.md headings · 137 lines, 1,171 words
SKILL.md preview
---
name: code-review
description: Use when reviewing a change before commit, merge or milestone sign-off — a working copy, a commit, a branch range or a PR. Produces a coverage ledger (every changed file reviewed or skipped with a reason) and severity-ranked, line-anchored findings, each re-checked before it is reported.
---

> **Skill by Mike Reams (2026-10-01, updated 2026-10-17).** Combines ideas from obra/superpowers
> `requesting-code-review` (MIT) and alibaba/open-code-review delegation mode + rule docs (Apache-2.0).
> See `NOTICE`. Read-only by default. Your project's instructions (`CLAUDE.md` or equivalent) win over
> this skill on any conflict.

# Code Review

Two failure modes this skill exists to stop:

- **Silent partial coverage.** On a 14-file change, the reviewer reads 6 files and says "looks good."
- **Noise.** Twenty nitpicks bury the one real defect, and line numbers drift off the code they describe.

The fix is deterministic bookkeeping around a judgment step. Lists, rules and coverage are mechanical.
Judgment is spent only on the diff.

## Step 1 — Fix the range

| Asked to review | Base / head |
|---|---|
| "my changes" / working copy | `git diff HEAD` + untracked files (`git ls-files --others --exclude-standard`) |
| a commit | `git show <sha>` |
| a branch / PR / milestone | `git merge-base main <branch>` → `<branch>` |

Get the file list with `git diff --name-status <base>..<head>` (plus untracked files for a working copy).

**Audit the change, not the repo** (added 2026-10-17): review the changed files plus whatever the change makes newly
reachable or newly wrong elsewhere (a new caller of an old function, a widened type, a route that now skips a guard).
Review the whole repository only for an app's first release or after a large refactor, and say which you did.

**Modes:**

| Mode | Writes | Output |
|---|---|---|
| `review` (default) | nothing | Steps 2-6 below |
| `check` (release gate) | nothing | Only disagreements between the app's shipping docs and its code over the range: each with the doc line and the code `file:line`, no fixes applied. Ends with one line: `docs-vs-code: N disagreements (C critical) · docs stale: <list or none>`. The owner decides whether the code or the doc is wrong |

## Step 2 — Build the ledger (before reading any diff)

One row per changed file: `path · status (A/M/D/R) · +/- · rule group · state`. Every row starts
`pending` and must end as `reviewed` or `skipped: <concrete reason>`.

Skip mechanically, never by taste:

| Skip | Reason to record |
|---|---|
| `pnpm-lock.yaml`, `package-lock.json`, `bun.lock` | lockfile (but review the `package.json` change that caused it) |
| `.next/`, `dist/`, `out/`, `coverage/`, `*.tsbuildinfo` | build output |
| Files a tool generated and the repo marks generated | generated, check the generator instead |
| Binary assets | binary, review only if the change is suspicious (size, name, location) |

**Do not skip** `baseline/` snapshots (e.g. `openapi.json`). They are the contract, and an unexplained
diff there is a finding. Do not skip migrations, `.github/workflows/`, `vercel.json` or `.env.example`.

## Step 3 — Attach rules to each file

| Path / type | Rules |
|---|---|
| every file | `rules/default.md` + `rules/estate.md` |
| `*.ts *.tsx *.js *.jsx *.mjs` | + `rules/ts-js.md` |
| `.github/workflows/*.yml` | + `rules/github-workflows.md` |
| `package.json` | + `rules/package-json.md` |
| `supabase/migrations/*.sql` | + `postgres-pro` skill (RLS, indexes, locking) |
| UI components | + `web-design-guidelines` for a11y/UX rules |
| anything in the app's `CLAUDE.md` "Regression gates" / "Review rules" / "Stop-and-ask tripwires" | **always** — app rules outrank the generic ones |

A tripwire hit (e.g. a hub change to key hashing, auth middleware or KV isolation) is reported as
**critical / stop-and-ask**, regardless of code quality.

## Step 4 — Review

**Preferred: a fresh-context reviewer subagent** (when the Agent tool is available). Fill
`reviewer-prompt.md` with the range, the requirement (SPEC milestone row or task text), the ledger and
the rule groups. Give it precise context, never this session's history.

**Otherwise inline**, in bounded passes grouped by rule group. Tick each ledger row as you finish it.

In both cases:

- Read the full file around a hunk when the hunk alone can't show correctness (callers, types, tests).
- Don't stop at the first high-severity finding.
- Large diff: say how many passes you ran.

### Step 4b — Intent axis: documented vs implemented (added 2026-10-17)

When the app keeps shipping docs (`templates/shipping/`: architecture, flows, permissions, variables, tests) or
equivalents under other names, treat them as **claims to verify**, not proof:

1. For each documented rule the change touches (who may do what, which boundary is trusted, what is public), find the
   enforcement point on the server, on every path. "Handled upstream", "admin only" and "internal" comments are not
   evidence; the code path is.
2. A mismatch matters when crossing it lets a real actor reach data, money, infrastructure or another user/tenant they
   shouldn't. Drift that only affects the actor's own data is cosmetic; drop it.
3. **Documented but not enforced** is a finding on its own. **Enforced but not documented** is usually fine, but report
   the doc as stale.
4. Every intent finding states: the doc claim (quoted, with its file), the code reality (`file:line`), who could exploit
   it and who is harmed, and the fix. If you cannot cite both sides, it is a question to investigate, not a finding.
5. No shipping docs on a production or consulting app is itself the first finding (`docs`, `medium`).

## Step 5 — Re-check every finding before it is reported

For each finding, re-open `path:line` in the **head** revision and confirm three things: (a) the line
says what the finding claims, (b) the problem isn't already handled nearby (guard, caller, test), and
(c) the severity matches the actual effect. Fix drifted line numbers. **Drop anything you can't confirm.**
Report fewer, true findings, not many plausible ones.

## Step 6 — Report

Lead with the verdict, then findings, then the ledger summary.

**Verdict:** `Ready` · `Ready with fixes` · `Not ready` · `Stop-and-ask (tripwire)` plus one sentence why.

**Findings**, ranked most severe first:

| Sev | Category | File:line | Problem → effect | Fix |
|---|---|---|---|---|

- Severity: `critical` (data loss, security, broken contract, tripwire) · `high` (bug a user/caller hits)
  · `medium` (error-handling gap, perf, maintainability with real cost) · `low` (style/nit).
  **Omit `low` unless it is clearly worth the reader's time.**
- Category: `bug · security · performance · maintainability · test · accessibility · docs · other`.

**Ledger summary:** `N files · reviewed R · skipped S (reasons) · coverage R/(N−S mechanical skips)`.
Below 100% coverage of the reviewable files, the verdict cannot be `Ready`.

**Declined to judge:** behavior considered and set aside as out of scope, one line each with the reason
(so nothing is dropped silently).

## Step 7 — After the review

- **Fixing is not implied.** If the ask was "review", stop at the report and ask before changing code.
  If the ask was "review and fix", fix critical/high, describe medium, and leave low.
- Treat incoming findings (yours or anyone's) with `receiving-code-review`. Verify them; don't
  perform agreement.
- No "fixed / passing / ready" claim without fresh evidence (`verification-before-completion`): rerun
  the app's gate (`pnpm typecheck && pnpm lint && pnpm test`) after fixes.
Files in this package (10)
  • LICENSE-APACHE-2.0-open-code-review 11 KB
  • LICENSE-MIT-superpowers 1 KB
  • NOTICE 2 KB
  • SKILL.md 8 KB
  • reviewer-prompt.md 2 KB
  • rules/default.md 1 KB
  • rules/estate.md 2 KB
  • rules/github-workflows.md 3 KB
  • rules/package-json.md 1 KB
  • rules/ts-js.md 3 KB

Versions

RepositoryScoreLicence
This page · solventarchitect/skills100MIT
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 086b5f08ff2a (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

  • 90review-code
    Reviews a diff, branch or path against the project's rules, specs, API contract, security checklist and budgets, using the frontend, backend and security leads in parallel. Reports findings with file:line and severity; read-only unless --fix is approved. Use before /story-done,…
  • 100pr-review
    Review a pull request / merge request on any git host — GitHub, GitLab, Bitbucket, Azure DevOps, Gitea/Forgejo/Codeberg — or local branches and uncommitted work, on three separate axes: correctness & risk, the repo's own coding standards, and the linked spec/issue. Produces…
  • 90risk-scaled-review
    Reviewing a code change before merge or delivery: a branch, PR, diff or commit range, whether the user's or an agent's. Use when asked to review, check or look over changes for bugs, risks or readiness to merge, in any language.
  • 90dev10x:review
    Review your own branch changes before creating a PR. Reviews diff against base branch, runs automated checks, and produces structured findings with severity, file, line, and suggested fix. Works in attended (pick findings) or unattended (auto-advance to fixer) mode. TRIGGER…
  • 100code-review-workflow
    Review a change in a fixed order — context, correctness, security, then style — and write feedback that is actionable and ranked by severity. Use when the user asks for a code review, wants a pull request or diff reviewed before merge, asks whether a change is safe to ship, or…
  • 100code-review-branch
    Review the entire current branch against its base (`origin/develop` if it exists, else `origin/main`) — every commit on the branch plus any uncommitted local work — as a pre-PR full-branch audit. Use when the user wants their whole branch reviewed before opening a PR or merging,…

Feedback and reports

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