/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 audits the diff against it, returning a structured PASS/FAIL report with severities. 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 manifest gate's body activates this skill with the dimension under `/do`'s selected evaluator; the gate names the dimension and this skill owns the threshold. If no dimension is given, list the available dimensions and ask which one — one invocation, one dimension.

Dimensions and thresholds

Load `references/<dimension>.md` for the requested dimension and follow it. The threshold is the bar a change must clear to PASS on that dimension:

| Dimension | Reference | Role | Threshold (PASS requires) | |-----------|-----------|------|---------------------------| | `change-intent` | `references/change-intent.md` | defect-finder | no LOW-or-higher findings | | `code-bugs` | `references/code-bugs.md` | defect-finder | no LOW-or-higher findings | | `contracts` | `references/contracts.md` | defect-finder | no LOW-or-higher findings | | `type-safety` | `references/type-safety.md` | defect-finder | no LOW-or-higher findings | | `defect-class` | `references/defect-class.md` | defect-finder | no LOW-or-higher findings | | `operational-readiness` | `references/operational-readiness.md` | advisory | no MEDIUM-or-higher findings | | `code-design` | `references/code-design.md` | advisory | no MEDIUM-or-higher findings | | `code-maintainability` | `references/code-maintainability.md` | advisory | no MEDIUM-or-higher findings | | `code-simplicity` | `references/code-simplicity.md` | advisory | no MEDIUM-or-higher findings | | `code-testability` | `references/code-testability.md` | advisory | no MEDIUM-or-higher findings | | `test-quality` | `references/test-quality.md` | advisory | no MEDIUM-or-higher findings | | `docs` | `references/docs.md` | advisory | no MEDIUM-or-higher findings | | `prose-value` | `references/prose-value.md` | advisory | no MEDIUM-or-higher findings | | `context-file-adherence` | `references/context-file-adherence.md` | advisory | no MEDIUM-or-higher findings |

The split is structural: **defect-finders** report only divergences/defects/contract-mismatches/type-holes that name their trigger — every LOW there is real signal. **Advisory** dimensions surface taste-level improvements where LOW is usually could-be-better, not is-broken.

**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 asks whether the fix accounted for every site its mechanism reaches, so on a change that fixes nothing it has no input and nothing to judge. Requesting it anyway is not an error; it reports PASS and says no fix was found in scope.

Determining scope (shared across dimensions)

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. 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 clarify scope.

Stay within scope — never audit the whole project unless explicitly asked. Skip generated files (`*.generated.*`, `generated/`, `dist/`, `build/`), lock files, vendored deps (`vendor/`, `node_modules/`, `third_party/`), and binaries.

**Reading scope ≠ reporting scope.** The diff bounds what you *report* (defaults: only issues introduced or exposed by the change). It does not bound what you *read* — trace mechanisms wherever they lead (existing callers, shared state, upstream writers) so boundary issues between changed and unchanged code stay visible. Read widely; report narrowly.

This skill is **read-only**: never modify repository files; write only to `/tmp/` for analysis artifacts. The author implements fixes from your report.

Severity ladder (shared)

• **Critical** — blocks release: data loss, corruption, security breach, or complete failure for all users; no workaround.
• **High** — blocks merge: core/happy-path functionality broken for common inputs.
• **Medium** — edge cases, degraded behavior, or failures needing multiple preconditions.
• **Low** — rare scenarios with workarounds, or (for advisory dimensions) taste-level could-be-better.

Each dimension's reference refines these with domain-specific calibration — defer to it.

Report format (shared)

# Code Review — <dimension>

**Dimension**: <dimension>
**Threshold**: no LOW+ | no MEDIUM+
**Status**: PASS | FAIL
**Files analyzed**: [...]

## Findings
### Finding #1: [title]
- **Location**: `file:line`
- **Severity**: Critical | High | Medium | Low
- **Description**: [what's wrong]
- **Trigger**: [the condition under which the defect manifests — the concrete input, state, or sequence that produces the failure, or for a static mis