/review-code

name: review-code
description: 'Review a change along one specific quality dimension — bugs, design, simplicity, maintainability, testability, test quality, type safety, contracts, operational readiness, docs, prose value, change intent, defect-class completeness after a fix, or context-file adherence. Loads exactly one dimension reference and reports findings graded by consequence; applies a caller-supplied acceptance policy when a gate verdict is requested. Use when verifying a change before merge, auditing a diff for a named concern, or running a manifest acceptance gate.'
user-invocable: true

review-code — one dimension per invocation

Audit a change along **one** review dimension and report findings. Load only that dimension's reference.

Input

`$ARGUMENTS` carries the **dimension** plus optional scope, e.g. `dimension=code-bugs` or `code-bugs src/foo.ts`. A caller requesting a gate verdict also supplies the claims to assess and any deliberately required severity, category or approval policy. A Manifest gate carries its claim and source authority; its Evidence names the dimension. If no dimension is given, list the available dimensions and ask which one — one invocation, one dimension. With no one to ask, report BLOCKED: no dimension was named, and naming one settles it.

Dimensions

Before reviewing a change in a project, read the project context file's pointers to principles skills — project skills named `<area>-principles` holding how the project's people want one area's work done — and load each one for an area the change touches (`../setup-project/references/PRINCIPLES_SKILLS.md` → *Using one*). Load `references/<dimension>.md` for the requested dimension and follow it. Its standards are opinionated defaults: where a rule the user stated, in the session or a context file, a principle in a loaded principles skill, or a convention the project states or documents (not a pattern its code merely repeats) differs, that rule governs, a change following it raises no finding, and the report names the rule applied — except a Critical finding on the ladder below, which is still reported, naming the rule that produced it. Classify findings by consequence; the caller chooses the acceptance threshold and handling policy.

| Dimension | Reference | Role | |-----------|-----------|------| | `change-intent` | `references/change-intent.md` | defect-finder | | `code-bugs` | `references/code-bugs.md` | defect-finder | | `contracts` | `references/contracts.md` | defect-finder | | `type-safety` | `references/type-safety.md` | defect-finder | | `defect-class` | `references/defect-class.md` | defect-finder | | `operational-readiness` | `references/operational-readiness.md` | advisory | | `code-design` | `references/code-design.md` | advisory | | `code-maintainability` | `references/code-maintainability.md` | advisory | | `code-simplicity` | `references/code-simplicity.md` | advisory | | `code-testability` | `references/code-testability.md` | advisory | | `test-quality` | `references/test-quality.md` | advisory | | `docs` | `references/docs.md` | advisory | | `prose-value` | `references/prose-value.md` | advisory | | `context-file-adherence` | `references/context-file-adherence.md` | advisory |

Roles define what to look for. **Defect-finders** report divergences, defects, contract mismatches and type holes with a stated trigger. **Advisory** dimensions assess product and quality gaps. Both use the shared severity ladder; neither role decides which findings the caller must address.

**Some dimensions are conditional**, and the caller decides whether they apply before requesting them: `contracts` where the change touches API surfaces or durable data contracts, `type-safety` on typed code, and `defect-class` where the change **fixes a defect**. `defect-class` is the one dimension that takes a defect as input rather than producing one as output — it judges the repair's protection against the demonstrated mechanism and accounts for affected sites, so on a change that fixes nothing it has no input and nothing to judge. Requesting it anyway is not an error; it reports no fix found in scope and applies any supplied acceptance policy.

Determining scope (shared across dimensions)

For a requested follow-up, the caller supplies the prior assessed state and criteria, findings, supported dispositions, verified repairs, and changes since that evaluation; use what applies. Criteria that changed since that evaluation make this a fresh review, scoped as below, since work the old criteria did not reach has never been reviewed. Otherwise report outstanding findings and failures introduced or exposed by the intervening changes, with evidence for which prior findings are repaired. Read context as widely as needed; an old issue on a touched line is not new merely because the line changed. If the needed prior state is missing, recover it or report BLOCKED with what is missing, rather than silently reviewing the complete change again. A new ID or repeated assertion does not reopen an evidenced disposition; changed code, criteria, argument or evidence can. Assess its support independently rather than requiring agreement with a previous reviewer.

For a fresh review — including a new standalone review when an earlier report exists — resolve its scope as follows:

1. **Caller specifies files/paths** → review exactly those. 2. **Otherwise** → review the complete change. Resolve the comparison base from the PR target or the repository's remote default branch; ask only if neither can be established, and with no one to ask report BLOCKED naming the base that could not be established. Inspect committed changes with `git diff <base>...HEAD`, staged changes with `git diff --cached`, unstaged changes with `git diff`, and relevant new files from `git ls-files --others --exclude-standard`. Read each new file's contents; a path listing alone is not its diff. 3. **Empty / non-reviewable diff** → ask the caller to clar