Skip to content
Skills Library
Programming · Review & audit

review-code

/review-code

Reviews code for design issues that static analysis misses — single responsibility, abstraction levels, testability, meaningful naming, API design, and error-handling strategy. Use when asked to review code, audit a module, check architecture or design, find design problems, improve code quality, or look at testability/coupling/SRP. Also invoke when a user says things like "review this code", "is this well-structured", "audit src/X for design problems", "what's wrong with this module", "check the architecture here", "look for SRP violations", "is this testable", or asks for a design-level (not

Repository
lumber-mart ↗
Licence
MIT
Last repository change
14.10.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
26
Scripts
20
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

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

Scripts: evals/fixtures/go-checkout/auth.go, evals/fixtures/go-checkout/handler.go, evals/fixtures/go-checkout/pricing.go, evals/fixtures/go-checkout/repo.go, evals/fixtures/go-checkout/service.go, evals/fixtures/py-clean/pricing/__init__.py, evals/fixtures/py-clean/pricing/convert.py, evals/fixtures/py-clean/pricing/errors.py, evals/fixtures/py-clean/pricing/rates.py, evals/fixtures/py-worker/worker/__ini

What it does and when to use it

Reviews code for design issues that static analysis misses — single responsibility, abstraction levels, testability, meaningful naming, API design, and error-handling strategy. Use when asked to review code, audit a module, check architecture or design, find design problems, improve code quality, or look at testability/coupling/SRP. Also invoke when a user says things like "review this code", "is this well-structured", "audit src/X for design problems", "what's wrong with this module", "check the architecture here", "look for SRP violations", "is this testable", or asks for a design-level (not

Triggers from the description

review this codeis this well-structuredaudit src/X for design problemswhatcheck the architecture herelook for SRP violationsis this testable
Original author description

Reviews code for design issues that static analysis misses — single responsibility, abstraction levels, testability, meaningful naming, API design, and error-handling strategy. Use when asked to review code, audit a module, check architecture or design, find design problems, improve code quality, or look at testability/coupling/SRP. Also invoke when a user says things like "review this code", "is this well-structured", "audit src/X for design problems", "what's wrong with this module", "check the architecture here", "look for SRP violations", "is this testable", or asks for a design-level (not

How it works

  1. Arguments
  2. Scope
  3. Severity, anchored on a named consequence
  4. What not to flag
  5. Do not drop a correctness defect because this is a design review
  6. Collapse patterns, then cap at ten
  7. When the code is sound, say so
  8. Output
Original SKILL.md headings · 113 lines, 1,941 words
SKILL.md preview
---
name: review-code
description: Reviews code for design issues that static analysis misses — single responsibility, abstraction levels, testability, meaningful naming, API design, and error-handling strategy. Use when asked to review code, audit a module, check architecture or design, find design problems, improve code quality, or look at testability/coupling/SRP. Also invoke when a user says things like "review this code", "is this well-structured", "audit src/X for design problems", "what's wrong with this module", "check the architecture here", "look for SRP violations", "is this testable", or asks for a design-level (not lint-level) read of a file or directory.
---

# Code Review

Review the code in scope for design and architecture problems.

> [!IMPORTANT]
> Consult [REFERENCE.md](REFERENCE.md) for the expected output format and level of detail.

You already know what bad design looks like — a function with two unrelated reasons to change, business rules interleaved with transport parsing, a constructor that reaches out and builds its own dependency, an API that must be called in an order nothing enforces, a name that describes a category instead of an action, an error path that collapses three different failures into one. Apply that judgement directly and thoroughly; reading the code closely is the bulk of the value here.

What follows is only the local policy you could not infer. Prescribing the review itself made reviews worse, not better: a 249-line version of this skill scored 78.4% across four fixtures against 94.5% for this one, with five times the variance, because attention went to restating design criteria instead of reading the code.

## Arguments

Your input may carry flags alongside a path. Strip the flags first; whatever remains is the path.

- **`--json <path>`** — additionally write a findings file at that path, per [FINDINGS.md](FINDINGS.md). Off by default; the markdown report is unchanged either way.
- **`--non-interactive`** — ask no questions. Where this skill would otherwise prompt, report the outcome and stop.

## Scope

Determine the review scope before discovering files. The discovery script ships in this skill's own `scripts/` directory — resolve it against this skill's directory rather than hardcoding an install path, which only holds for one harness's layout:

```bash
DISCOVER="<this skill's directory>/scripts/discover-files.sh"
```

- If a path was given, treat it as a path (file or directory) and run:
  ```bash
  bash "$DISCOVER" <path>
  ```
- If no path was given, scope to files added or modified on the current branch relative to the default branch:
  ```bash
  bash "$DISCOVER"
  ```

Handle the script's exit codes:
- **0 with output** — review the listed paths.
- **0 with empty output** — nothing is in scope. Interactively, say so and ask which path to review; under `--non-interactive`, report `no_scope` and stop.
- **non-zero** — the script explains itself on stderr (path not found, not a git repo, on the default branch with no path, detached HEAD, or default branch indeterminate). Relay that message, then ask which path to review, or under `--non-interactive` report `error` with the message and stop.

A review that ran and found nothing, and a review that never ran, both end with zero findings and mean opposite things — so say which happened, in the report and in the findings file's `status`. A caller that cannot tell them apart reports a broken pipeline as a clean codebase.

The script returns paths language-blind. Filter to source files, dropping tests, vendored and generated code, and pure configuration.

For five or more source files — or fewer large ones — fan out if delegation is available:
give each subagent a couple of files, the severity rules below, and the named-consequence
requirement. Otherwise review the same files sequentially. Keep delegated reviews to static
reading: use available file-reading/search tools, including terminal commands when needed,
but do not execute project code. Merge what comes back before collapsing patterns.

## Severity, anchored on a named consequence

These findings feed a work-tracking pipeline, so an inflated severity becomes false urgency in someone's backlog and teaches people to ignore the reviewer. The driving question for every finding: **name a specific change someone is likely to make that this design would predictably break.** State it concretely — *"adding a CLI entry point would force re-implementing the discount tiers currently inlined in the HTTP handler."* A finding you cannot put in that form is below the bar; drop it, and do not demote it to P3 because it sounds mild. P1 is the exception: its consequence is implicit.

- **P1** — a security flaw in the design, or code with no test seam at all. Authorization decided from caller-controlled input, a privileged operation with no check, a secret or credential that escapes into a response or a log. Or: no way to substitute a dependency, even with the language's standard mocking tools.
- **P2** — a change someone is likely to make goes wrong. An SRP violation where you can name the ripple ("a pricing rule change lands in the same function as a validation rule change"). Mixed abstractions where you can name the entry point the mixing blocks. Temporal coupling that nothing enforces, with the misuse named. Divergent shapes across sibling APIs, where you name the consumer that cannot share code. Testability friction whose cost you can state as a test that cannot be written cleanly.
- **P3** — the same shape, but the named consequence is narrower: it misleads a reader, or costs readability rather than future change. Naming and small API asymmetries usually live here.

P1 is narrower than it looks, and it is the severity that drifts. Where the language has monkeypatching — Python, TypeScript — a module-scope singleton is almost never a testability P1: `monkeypatch.setattr` or `vi.mock` is the seam, so it is friction, not a wall. Reserve it for the design where you can name no seam at all, and for security flaws you can trace from an attacker-controlled input to the privilege it buys. If a report carries more than one P1, be suspicious of the second.

The P2/P3 line: does the named consequence hit a change someone is **likely to make**, or only a **reader's first impression**? A design that forces a future refactor to land in many places is P2; one that merely reads awkwardly is P3.

## What not to flag

Each of these spends the reader's attention on something they cannot act on, or on a decision they already made:

- **Anything the toolchain already prints.** Linters, formatters, type checkers and security scanners run alongside this review, and they own function length, nesting depth, cyclomatic complexity, dead code, formatting, type errors, injection and hardcoded secrets. If a linter would flag it, it is not a design finding. Where those tools appear to be missing, say so once in the report rather than filing their findings by hand.
- **A test defect rather than a code defect.** A weak assertion or a missing case is a real observation and the wrong review; it belongs to a test review.
- **Anything under `fixtures/`, `testdata/`, `__fixtures__/`, or `golden/`.** Those files are deliberately shaped input, and their defects are usually the point.
- **A missing abstraction nothing yet needs.** An interface with one implementation, a config value not yet configurable, a layer someone might want later — speculative generality costs more than it saves, and asking for it lands on code that is currently right.
- **An alternative idiom the codebase has already chosen.** Raising versus returning an error, constructor injection versus a factory, a protocol with a single implementation: a defensible convention consistently applied is not a defect. Flag inconsistency, not preference.

## Do not drop a correctness defect because this is a design review

The framing here pulls attention toward structure, and the cost shows up in one particular
blind spot: an operation that is not idempotent in a world that will retry it. A refund
`UPDATE` with no already-refunded guard, a retry loop that mints a fresh idempotency key on
every attempt, a batch job that recharges on re-run. These sit in the seam between structure
and behaviour, so a reviewer looking for responsibilities and abstraction levels reads past
them — in testing, unskilled reviews caught these and design-focused ones did not.

When you notice a defect like that, file it with the same named-consequence discipline as
everything else. The reader does not care which review was supposed to catch it. This is not
licence to file every bug you can find: it applies to what you noticed while reading for
design, not to a hunt for logic errors, which is a different review.

## Collapse patterns, then cap at ten

N findings for N instances of one anti-pattern is noise. When several findings share a root cause — three route modules each constructing their own connection pool at import scope, business rules inlined at every transport boundary, every repository leaking its driver's row type — collapse them into **one** finding that names the pattern, lists the affected locations, and prescribes the codebase-wide fix, at the highest severity among them. Keep findings separate when they merely share a category.

Then cap the report at ten. It is a ceiling, not a target: four real findings means a four-finding report, and landing on exactly ten more than once is a sign of padding rather than a coincidence. Include every P1 — they never belong in a truncated tail — then fill with P2s and P3s by impact, favouring the ones whose consequence reaches more callers. If you cut any, end with `Note: N additional findings omitted (X P2, Y P3) — re-run after addressing these to surface what remains.`

When the cap binds, keep the finding that names the largest structural problem even if several smaller ones are easier to write up. A unit doing four unrelated jobs is worth more to the reader than three separate notes about its consequences, and it is the finding most easily crowded out — symptoms are more concrete than their cause, so they win the budget unless you watch for it.

Design changes have wider blast radius than test fixes, so churn matters more here, not less. A thirty-finding review is unmergeable as one PR; it ages out or gets half-applied. Batches of ten are what people actually do, and re-running after fixes surfaces what only became visible once the pressing things were gone — often one cross-cutting refactor dissolves several adjacent findings. The cap also works against the "asked to find things, so finds things" reflex.

## When the code is sound, say so

A review that finds little should read as a verdict, not as a shrug. Reporting only issues is the right default, but on well-designed code a bare count line leaves the reader unable to tell a careful review from a cursory one, and the next thing they do is ask whether you actually looked. Say plainly that the design holds up and name what carries it — the injected dependencies, the single-purpose modules, the error type that gives callers something to branch on. Two sentences is enough. Then file the one or two real findings if there are any, and stop; do not reach for filler to make the report look substantial.

## Output

Produce a report following the structure in [REFERENCE.md](REFERENCE.md). Each finding must include:

- **Priority** (P1/P2/P3) in the H3 header
- **Location** (file:line)
- **Explanation** of the problem and why it matters
- **Fix** — concrete prescription. For an API design issue, give the exact shape: parameter names, types, signatures, not just the general approach.
- **Done when** — a criterion verifiable by reading the diff, referencing specific functions, files or observable behaviour. "Both parseSkillFrontmatter and parseAgentFrontmatter delegate to a shared parseFrontmatterRaw; no duplicated delimiter-scanning code remains." NOT: "the duplication is removed."

When `--json <path>` was given, write the findings file described in [FINDINGS.md](FINDINGS.md) as well. Two fields need care because nothing downstream can recover them if they are wrong: `files` must list every path a finding touches, and `pattern` must be the slug that names its root cause, taken from the vocabulary in [REFERENCE.md](REFERENCE.md). Findings you collapsed together share a root cause, so they share a slug — that pairing is what lets a later run recognise this finding as one it has already reported.
Files in this package (26)
  • FINDINGS.md 4 KB
  • REFERENCE.md 5 KB
  • SKILL.md 12 KB
  • evals/README.md 8 KB
  • evals/evals.json 9 KB
  • evals/fixtures/go-checkout/auth.go 1 KB
  • evals/fixtures/go-checkout/handler.go 3 KB
  • evals/fixtures/go-checkout/pricing.go 1 KB
  • evals/fixtures/go-checkout/repo.go 2 KB
  • evals/fixtures/go-checkout/service.go 3 KB
  • evals/fixtures/py-clean/pricing/__init__.py 1 KB
  • evals/fixtures/py-clean/pricing/convert.py 3 KB
  • evals/fixtures/py-clean/pricing/errors.py 1 KB
  • evals/fixtures/py-clean/pricing/rates.py 2 KB
  • evals/fixtures/py-worker/worker/__init__.py 1 KB
  • evals/fixtures/py-worker/worker/batch.py 3 KB
  • evals/fixtures/py-worker/worker/billing.py 1 KB
  • evals/fixtures/py-worker/worker/client.py 1 KB
  • evals/fixtures/py-worker/worker/report.py 1 KB
  • evals/fixtures/ts-api/package.json 1 KB
  • evals/fixtures/ts-api/src/money.ts 2 KB
  • evals/fixtures/ts-api/src/server.ts 1 KB
  • evals/fixtures/ts-api/src/routes/orders.ts 2 KB
  • evals/fixtures/ts-api/src/routes/sessions.ts 1 KB
  • evals/fixtures/ts-api/src/routes/users.ts 1 KB
  • scripts/discover-files.sh 2 KB

Versions

RepositoryScoreLicence
This page · lumberbarons/lumber-mart100MIT
doodledood/manifest-dev100MIT
serpro69/claude-toolbox100Apache-2.0
serpro69/claude-toolbox100Apache-2.0
jelvodev/yaap100MIT
globalmindsolution/gms-marketplace100MIT
tojim00d/Orbit-skills100MIT
yaohuangguan/agent-playbook100MIT
paultyng/skill-issue100MIT

Database snapshot: 13.11.2026 · package version 40d3ef4b89c6 (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

  • 90testability-canary
    Testability and design decoupling canary — checks for tight coupling, lack of Dependency Injection (DI), hardcoded constructors, Single Responsibility Principle (SRP) violations, and mockability gaps. Triggers on keywords: "/testability-canary", "testability-canary",…
  • 90testability-canary
    Testability and design decoupling canary — checks for tight coupling, lack of Dependency Injection (DI), hardcoded constructors, Single Responsibility Principle (SRP) violations, and mockability gaps. Triggers on keywords: "/testability-canary", "testability-canary",…
  • 100clean-code
    Software quality review and design guidance for any code: naming, cohesion, coupling, duplication, function size, dependency direction, and testability. Use when someone asks to improve, review, refactor, or design code, or asks what good structure looks like here. Routes to the…
  • 100solid-principles
    This skill should be used when the user asks to "check SOLID violations", "audit class design", "review code quality", "find design smells", or "improve object-oriented architecture". Also triggers when the user mentions a principle by name (e.g., "check SRP", "is this violating…
  • 100clean-code
    Coding standards (SRP, DRY, KISS, YAGNI, naming) with a pre-edit dependency check and a completion self-check. Use when writing, editing or finishing code.
  • 1004r-code-review
    Perform structured code reviews using the 4R framework (Risk, Readability, Reliability, Resilience). Use this skill whenever the user asks to review code, audit a PR, check a diff, analyze a file for quality issues, or says anything like "review this", "check this code", "is…

Feedback and reports

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