Code Review

Code Review

Spawn a clean-context Claude subagent (code-reviewer) to adversarially review a file, directory, or git diff. The subagent returns findings as YAML; this skill formats them and (optionally) writes a review artifact.

Use this when:

• You want a second pair of eyes on a file before committing.
• You finished a build phase outside /build full and want a code-review.md-shape report.
• You want to review the last commit (/code-review with no args defaults to HEAD~1..HEAD).

Don't use this for:

• /build full Phase 6 — that pipeline still uses Agent(subagent_type: "reviewer", ...) internally, which writes .build/review.md in-flow. This skill is a sibling, not a replacement.
• Reviewing ideas or PRDs — use /panel for that.

Cost: Free-ish. The subagent uses your Claude Code plan tokens. No external API.

Step 0: Parse arguments

$ARGUMENTS shapes:

Flags (any order):

• --against <path> — also pass <path> to the reviewer as alignment spec (PRD, tech spec, EARS acceptance criteria, etc.)
• --write <path> — after findings come back, render them into templates/code-review.md shape at <path>. Default: print to chat only.

If you can't tell whether an arg is a path or a git range, prefer path. Then fall back to git if the path doesn't exist.

Step 1: Resolve the target

For a path:

• Single file → read the file content.
• Directory → glob **/*.{py,ts,tsx,js,jsx,svelte,md,sh,yml,yaml,json} (or anything else obviously code), cap at 10 files. If more, list them in chat and ask the user to narrow.

For a git range:

• git diff <range> — capture the diff output.
• If the range is a single ref (HEAD, <sha>), expand to <ref>~1..<ref>.

Size guard: If the captured content exceeds ~50KB (roughly 1500 lines of source or 1000 lines of diff), warn the user, list the largest files, and ask which subset to review. Do not silently truncate.

Step 2: Spawn the reviewer subagent

Agent(
  subagent_type: "code-reviewer",
  description: "Code review <target>",
  prompt: <see below>
)

The prompt to the subagent has four parts:

1. Role primer (one line): "You are a clean-context senior code reviewer. Follow the checklist and YAML schema in your agent definition. Return ONLY the YAML block."
2. Target context: "Target: <path-or-range>. Project: OpenVera (personal AI workbench, Markdown + Python harness scripts + Claude Code skills)."
3. The content: The file content OR the diff output OR (for directories) each file's content concatenated with a # === <path> === separator.
4. (Optional) Spec: If --against <spec> was provided, append "Alignment spec follows. Compare the target against this:" plus the spec content.

Keep the prompt under ~100KB total. The agent's checklist + schema live in its definition file, so don't restate them — just remind it to follow them.

Step 3: Receive + display findings

The subagent returns a YAML block. Parse it.

Print to chat in this shape:

**Verdict:** <pass | pass-with-findings | fail>  ·  C: <n>  H: <n>  M: <n>  L: <n>
**Summary:** <one_liner from YAML>

### Critical
| # | File:Line | Finding | Fix |
|---|-----------|---------|-----|
| C1 | path:12 | <finding> | <fix> |

### High
... (same shape)

### Medium
...

### Low
...

Empty severity sections: omit the heading + table entirely (don't print empty headers).

If the YAML doesn't parse, surface the raw output and a one-line "subagent returned non-YAML — re-run with a smaller target or tighter prompt." Don't try to repair the YAML — the subagent should obey schema; if it doesn't, the prompt needs tightening.

Step 4: Optional --write

If --write <output-path> was passed, write a Markdown file at that path matching .claude/skills/build/templates/code-review.md structure:

• Header (Reviewer: Vera, Date: today's date, Status from verdict)
• Review Summary (one_liner from YAML)
• Files Reviewed table (each file in the target)
• Findings — Critical / High / Medium / Low tables (same shape as Step 3)
• Checklist section: copy the checklist from the agent definition with each category marked ✓ (since the agent walks the full list)

Use the Write tool. Confirm the path is reachable (parent dir exists or is creatable).

Step 5: Gate line

Print a single closing line:

Verdict: <pass | pass-with-findings | fail>. <N> Critical, <N> High. Run again on a different target, or fix and re-run on the same one.

That's it. No follow-up questions. The skill is one-shot.

Author: Shareef Ellis · @shareefatwork

Source: Reef123/OpenVera — distributed by TomeVault.