Perform an in-depth code review of changed files and produce a structured report. Defaults to reviewing staged changes.
when_to_use
Use when the user asks to review code changes, requests a structured quality assessment covering logic, security, performance, and maintainability, or wants a detailed report with severity-ranked issues and fix suggestions. Defaults to reviewing staged changes but can target a specific file or directory.
tools
read, bash, glob, grep
args
[{"name":"target","description":"File or directory to review; leave empty to review git staged changes","required":false}]
GUIDANCE SKILL — INSTRUCTIONS ONLY
Code review is a systematic examination of source code quality across multiple dimensions: logic, security, performance, maintainability, and standards compliance.
This skill provides patterns, conventions, and constraints. It contains no executable code — apply the guidance to your context, adapting specifics as needed per C2-B.
CRITICAL: Guidance Principles
The instructions below define the REQUIRED APPROACH — you MUST follow the prescribed patterns, conventions, and constraints.
Mandatory adherence:
Follow all stated conventions and naming patterns
Respect all constraints and boundaries
Apply the recommended patterns to your implementation
Do NOT deviate from prescribed architectural decisions
Never modify any code; the review is strictly read-only
Every issue reported MUST include a concrete, actionable fix suggestion
Correct Application Pattern
Read and absorb all guidance sections below
Map the prescribed patterns to your current context
Implement following the stated conventions — adapt specifics to fit, but preserve the intent
Validate against the C3 checklist at the end
Argument Details
Arg
Type
Required
Default
Description
target
string
No
(empty)
File or directory to review; leave empty to review git staged changes
Design Patterns & Conventions
Architectural Pattern
Multi-dimensional assessment: every review MUST examine the target code through all five review dimensions — Logic Correctness, Security, Performance, Maintainability, and Standards Compliance. Issues from each dimension are independently classified and then merged into a single ranked report.
Naming Conventions
Issues are classified by severity using four standard levels:
Severity
Meaning
Critical
Security vulnerability, data loss risk, or production-breaking bug
High
Logic error with significant impact, or major performance regression
Medium
Maintainability concern, minor duplication, or unclear naming
Low
Style nit, non-critical lint warning, or cosmetic improvement
File / Module Organization
The output is a single structured Markdown report composed of:
An issue table with columns: Severity, File:Line, Description, Fix Suggestion
An overall score (1–10) with key areas for improvement
Issues in the table are ordered by severity (Critical first, then High, Medium, Low).
Data Flow
Determine scope (staged changes or {{target}})
→ Read all changed/in-scope files
→ Analyze against each review dimension
→ Classify each finding by severity
→ Merge and rank all issues
→ Produce structured Markdown report (table + score)
Constraints & Boundaries
Hard Constraints (non-negotiable)
Read-only: Never modify any code, files, or configuration. The review is purely observational.
Concrete fix suggestions: Every reported issue MUST include a specific, actionable fix suggestion — never flag a problem without offering a remedy.
All five dimensions: Every review MUST examine Logic, Security, Performance, Maintainability, and Standards Compliance. If a dimension yields no findings, explicitly note that.
Severity ranking: Every issue MUST be assigned exactly one severity level (Critical, High, Medium, Low).
Soft Guidelines (preferred but flexible)
Prefer concrete code examples in fix suggestions over abstract advice.
Prioritize security issues over performance issues when ranking within the same severity tier.
Include the project's lint command output when available; run lint as part of the review process.
Review surrounding context (not just the diff) to catch integration issues.
Implementation Guidance
Step-by-step Approach
Determine scope: If {{target}} is provided, scope to that file or directory. Otherwise, obtain git staged changes via git diff --staged.
Read all target files: Load every file in scope into context. For diffs, also read the full file to understand surrounding code.
Lint check: Run the project's lint command (e.g., npm run lint, eslint, golangci-lint) and capture violations.
Maintainability: Assess naming clarity, function length, duplicated code, comment quality, test coverage gaps.
Standards Compliance: Map lint violations to the report; flag any project convention deviations.
Classify and rank: Assign a severity to each finding. Sort Critical → High → Medium → Low.
Produce report: Build the Markdown issue table, compute the overall score (1–10), and list key improvement areas.
Key Decisions
Decision
Rationale
Trade-offs
Default to staged changes
Most common review use case; minimizes noise
May miss unstaged work in progress
Five review dimensions
Balanced coverage of quality attributes
Some overlap between Maintainability and Standards Compliance
Severity-ranked table format
Actionable, scannable, and easy to integrate into tooling
Less narrative context than prose
Table before score
Allows reviewer to derive score from issue inventory
Score may feel disconnected if table is long
Read-only enforcement
Prevents accidental modification during review
Cannot auto-fix trivial issues
Usage Notes
Input / Output
Input: A file path, directory path, or nothing (defaults to git staged changes). When {{target}} is specified, all files within that scope are reviewed. When omitted, git diff --staged determines the change set.
Output: A Markdown report containing:
An issue table with columns: Severity, File:Line, Description, Fix Suggestion — sorted by severity descending.
An Overall Score (1–10).
Key Areas for Improvement — a bullet list of the highest-priority action items.
Feature Support
Feature
Input
Output
Staged changes review
(empty target)
Diff-based report
Single file review
File path
Targeted report
Directory review
Directory path
Multi-file aggregated report
Lint integration
Project lint command
Lint violations in Standards Compliance
Edge Cases
Empty diff / no changes: Report "No changes to review" with score N/A — do not fabricate issues.
Binary files in scope: Skip binary files; note them as "skipped (binary)" in the report.
Very large files: If a file exceeds reasonable context size, review the diff portion only and note the limitation.
Files outside workspace: If {{target}} points outside the workspace root, report the error and halt.
Missing lint command: If no lint configuration is found, skip the Standards Compliance lint step and note that lint was unavailable.
Self-Check Before C3
Before running the formal C3 verification, confirm:
All five dimensions have been examined (even if some yielded no findings).
Every issue row has all four columns populated (Severity, File:Line, Description, Fix Suggestion).
The severity classification is internally consistent (no Critical issue ranked below a Low issue).
The overall score and key improvement areas are present.
No code has been modified.
Common Pitfalls
Over-adaptation: "Adapt specifics to fit" does not mean rewrite the core patterns. When in doubt, preserve the prescribed approach over local convenience — the patterns exist for a reason.
Pattern drift: As implementation progresses, it's easy to gradually deviate from conventions. Regularly re-read the Design Patterns section to catch drift early.
Surface-level review: Do not limit findings to style and lint issues. Deeply examine logic correctness and security — those are the highest-value dimensions of a code review.
Missing context: Reviewing only the diff lines without reading surrounding code can miss integration bugs. Always read enough context to understand how the change fits into the broader module.
Vague fix suggestions: "Fix the bug" or "Improve this" are not actionable. Every fix suggestion must be concrete — propose a specific code pattern, refactor, or library usage.
C3 Verification
Check Item
Constraint
Common Omission
Method
Pattern adherence
Prescribed patterns followed
Divergent implementation
Compare against Design Patterns section
Naming conventions
Conventions applied consistently
Inconsistent naming
Grep / code review
Hard constraints
All non-negotiable constraints met
Constraint violation
Manual checklist verification
File organization
Modules/files structured as prescribed
Misplaced or missing files
Directory structure review
All dimensions covered
Five review dimensions examined
Missing Security or Performance
Cross-reference report against Review Dimensions
Issue format complete
Every issue has Severity + File:Line + Description + Fix