code-review

name	code-review
description	Review committed changes on the current branch against project standards, security, simplicity, and architectural fit. Invoked as the `/code-review` slash command. Default range is `origin/main..HEAD`; pass a SHA or range as an argument to scope the review. Runs read-only via a sub-agent; the parent then proposes fixes interactively.

Code Review

Universal code-review skill for maelstrom projects. Reviews a range of commits for project-standards conformance, security, simplicity, and reuse, and reports findings back to the user. The parent agent (this skill's top-level section) drives the workflow; a read-only sub-agent does the actual review against a structured Markdown contract.

Stateless and one-shot. Re-invoke /code-review after a fix commit lands to re-review — there is no incremental-review machinery, no resolved-thread tracking, no JSON output.

Parent-agent section (runs on /code-review)

This is what runs when the user types /code-review. Follow these steps in order.

1. Gate the review and resolve the range

Run:

mael review-prepare $ARGUMENTS

$ARGUMENTS is the user's argument string (may be empty). The command handles range resolution (default origin/main..HEAD; a bare SHA expands to <sha>^..<sha>; anything else is passed to git as-is) and the pre-flight gates (aborts if the worktree has uncommitted changes or the range is empty).

If the command exits non-zero, print its stderr to the user and stop — do not spawn the sub-agent.

On success, capture stdout. It contains a Range: header followed by the two git log and git diff commands the sub-agent should run itself. The diff stays out of the parent's context.

2. Spawn the review sub-agent

Read the reviewer prompt from reviewer-prompt.md (alongside this file, at ~/.claude/skills/code-review/reviewer-prompt.md).

Use the Task tool with subagent_type: "Explore" (read-only — matches the brief: no edits, no tests, no builds; it can run git log / git diff via Bash). The sub-agent prompt is the contents of reviewer-prompt.md followed by the captured output of mael review-prepare from step 1.

3. Display the sub-agent's response

The sub-agent returns Markdown. Re-display it to the user verbatim, preserving section order:

1. ## Summary
2. ## Design decisions worth calling out
3. ## Blocking findings
4. ## Advisory findings

4. Resolve Blocking findings interactively

For each entry under Blocking findings:

• Propose the specific fix to the user (use AskUserQuestion or a plain prompt — your call based on fix complexity).
• Do not auto-apply. Wait for explicit approval before editing.
• Apply approved fixes via Edit/Write.

Advisory findings: apply only the ones that are clearly correct and low-risk in your judgement. Skip the rest. State briefly which advisories you addressed and which you skipped.

5. Commit the fixes

For each blocking finding that was fixed, create one fixup commit targeting the commit that introduced the issue. The sub-agent's findings are reported against specific commits in the range, so the target SHA is available per finding:

git add -- <paths relevant to this finding>
git commit --fixup=<sha>

Stage only the files relevant to that finding before each fixup so the fixups stay aligned with their target commits.

If a fix can't be attributed to a single commit in the range (e.g. it spans multiple commits), fall back to git commit --fixup=HEAD and call that out in the report.

Hard rules:

• Never --amend existing commits.
• Don't run the autosquash rebase yourself — leave that to the user (mael sync --squash or git rebase -i --autosquash).

6. Done

Report what was fixed. The user can re-invoke /code-review to re-review if they want — this skill is stateless.

Do NOT bake project-specific rules into this skill

This is the universal review skill. Project-specific rules belong in docs/review/coding-standards.md / docs/review/code-smells.md, not here — reviewer-prompt.md tells the sub-agent to load them conditionally. The following are examples of things that must not appear in either this file or reviewer-prompt.md:

• Q() / %s SQL placeholders or any other framework-specific API.
• No-Tailwind, project-CSS-utilities, or any other UI-framework rule.
• NZ English / locale-specific copy rules.
• SystemModel / AppModel / handler-vs-model architectural splits.
• unittest-vs-pytest test framework preferences.
• File-type→skill mappings beyond the generic "load skills matching diff file types".
• Severity tables enumerating project-specific blocking rules.

Also out of scope:

• Incremental-review mode / resolved-thread tracking.
• GitHub PR comment posting or any CI-gate-specific output (JSON contract, resolve_thread_ids, inline-anchor rules).
• GraphQL thread IDs.
• The autosquash rebase itself — the parent creates fixup commits but leaves mael sync --squash (or git rebase -i --autosquash) to the user.