/code-review

name: code-review
description:
  'Run a comprehensive code review on local source files. Use this skill when the user asks to review, audit, inspect,
  evaluate, or check code, even if they never use the word "review." Does not post comments to GitHub pull requests —
  use post-code-review-to-pr for that. Does not analyze architectural structure or module boundaries — use
  architectural-analysis for that. Does not explain code or a PR to build understanding before reviewing — use
  code-overview for a written overview, or code-walkthrough to be paced through it one step at a time. Does not capture
  feedback on Han''s own skills — use han-feedback for that.'
arguments: size
argument-hint: "[size: small | medium | large | dynamic] [optional context about changes or areas to focus on]"
allowed-tools:
  Bash(git *), Bash(gh *), Bash(make *), Bash(npm *), Read, Write, Grep, Glob, Agent,
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

When running a code review, follow the process outlined here.

Project Context

• git installed: !`which git 2>/dev/null || echo "not installed"`
• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Review Constraints

Severity levels:

• **Critical** — Must fix before merge. Security vulnerabilities, data corruption risk, breaking API changes, data

isolation failures.

• **Warning** — Should fix. Bugs that don't corrupt data, significant performance issues, missing required tests,

missing error handling.

• **Suggestion** — Consider improving. Style improvements, optional performance gains, documentation gaps, refactoring

opportunities.

Severity calibration is governed by **Step 3.3** (the authoritative home for size-based demotion). Manual findings from Steps 4 to 6 follow the same size-based rules as agent findings classified at Step 7: Small changes escalate only Critical findings and default uncertain ones to the lower severity, Medium changes escalate Critical and Warning, Large changes prefer the higher severity when in doubt. Read `{size}` from Step 3.1. Include `file_path:line_number` references and code examples for suggested fixes.

**Finding caps:** Manual review findings (Steps 4-6) and agent findings (Step 7) are each capped at 30 items. Prioritize by severity: all CRIT first, then WARN, then SUGG. If either cap is exceeded, note that additional items were omitted and another code review is recommended after addressing current items. Security findings are not capped (see classification rubric).

**Project pattern deference:** A pattern that differs from general best practices but is consistent within the project is not a review finding. Only flag deviations from the project's own conventions.

**YAGNI findings are a separate, non-correcting class.** Apply the two-pass YAGNI procedure documented in [`references/review-checklist.md`](./references/review-checklist.md) (the canonical home for the procedure and the (a)/(b)/(c) recording requirement) to every change in the diff. **YAGNI findings are listed in their own `### 🟡 YAGNI` section, separate from Critical / Warning / Suggestion**, and **do not appear under CRIT / WARN / SUGG**. The YAGNI section opens with this exact statement: _"These findings will not be corrected unless explicitly requested. They are documented so the team can decide consciously whether to keep, simplify, or defer the items."_ Severity calibration (the directive in Step 3.3, the authoritative home) does NOT apply to YAGNI; these findings are surfaced regardless of change size and are advisory, not corrective.

**Automated tool boundary:** If the project has a linter or formatter, trust it. Only flag style issues that automated tools can't catch.

**Readability standard:** The review report is a reader-facing deliverable. As it writes the finding prose and narrative, the skill sources the shared standard by invoking `han-communication:readability-guidance` (Step 8) and applies it, holding the named audience: the author and reviewers of the change under review. The standard governs how each finding reads (lead with what to do and why, one idea per paragraph, short active sentences, plain words), and drops a required technical fact only when the reader asked for less and losing it would not change what they do next. It applies to the prose in finding bodies and narrative sections only; it never rewrites task IDs, severities, `file_path:line_number` references, `EXPLOIT:` fields, category labels, the fixed section headings and their order, the Review Summary table structure, or any code snippet. The dedicated `han-communication:readability-editor` rewrite (Step 8.5) and the readability self-check (Step 9.2) carry the standard into the report.

Task ID Assignment

Assign a unique task ID to each review item:

• **CRIT-###** for critical items (e.g., CRIT-001, CRIT-002)
• **WARN-###** for warnings (e.g., WARN-001, WARN-002)
• **SUGG-###** for suggestions (e.g., SUGG-001, SUGG-002)
• **YAGNI-###** for YAGNI candidates (e.g., YAGNI-001, YAGNI-002) — these are advisory and listed in their own section;

they are not corrected unless the user explicitly requests it

IDs are sequential within each category, starting at 001. Assign IDs in the order files are reviewed (a