Skill: /code-review

Trigger

/code-review "description of what was implemented"

The description is optional but allows validating the flow before analyzing the code.

Response guidelines

Be comprehensive but concise. Omit obvious explanations, get straight to the point. Save tokens without losing technical precision. Prefer short bullets to paragraphs.

Reading project context

Read if they exist:

.claude/project.md — stack, environments, modules
.claude/conventions.md — mandatory team standards
.claude/architecture.md — expected architectural patterns
.claude/known-issues.md — to identify recurring issues

Stage 0: Clarification

Before reviewing, check if there is sufficient context to perform an accurate review.

Ask up to 3 targeted questions if any of the following are true:

No description was provided AND no open files / diff / PR context is visible
The described behavior contradicts what the code appears to do (needs confirmation of intent)
The review scope is undefined (e.g., a very large diff with no indication of which areas matter most)

Do not ask style or preference questions. Only ask when missing context would produce an inaccurate review.

After asking, wait for the user's reply before proceeding to Stage 1. If the user says "skip questions" or "just review", proceed immediately.

Stage execution

By default, all stages run sequentially in one response.

The user can say "do only Stage 1 and 2", "stop after Stage 2", "skip to Stage 4". Respect this literally.

If during a stage a critical ambiguity appears (e.g., a pattern that could be intentional or a bug), flag it inline as:

Question before continuing: [question]. If not answered, proceeding with conservative assumption: [stated assumption].

Stage 1: Flow validation

Before analyzing the code (only if description was provided):

Understand the described flow
Identify logical gaps, uncovered cases, questionable approach
Issue verdict: ✅ Sound / ⚠️ With caveats / ❌ Problematic

Do not reject based on aesthetic preference — only real functional or security problems.

Stage 2: Code analysis

🔴 Critical — Blocks the PR

Security vulnerabilities (SQL injection, exposed data, bypassable auth)
Data loss (delete without soft delete when expected, accidental truncate)
Race conditions in jobs/queues
Migrations without down() or that lock large tables
Hardcoded secrets or credentials
Breaking API contract without versioning
Logic that directly contradicts the stated requirement

🟡 Important — Must be fixed before merge

Violation of team conventions (.claude/conventions.md)
Missing error handling at critical points
N+1 queries or heavy operations inside loops
Job/command not idempotent when it should be
Missing input validation on public endpoint
Violation of project architectural patterns

🟢 Suggestion — Optional improvement

Opportunity for reuse
Confusing but functional naming
Possible simplification without risk

If more than 3 critical items are found and the scope of change is unclear, pause after listing them and ask: "Found N critical items. Continue with Important/Suggestion items, or stop here to address these first?"

Stage 3: Recurring issues detection

Check if any problem found already exists in .claude/known-issues.md or is new with recurring potential.

Automatic known-issues update

If new and recurring, add to .claude/known-issues.md:

## [Problem Category]

Description: problem found.
Context: where it tends to appear.
Solution: how to resolve or prevent.
Detected in: [code-review]

Inform: "⚠️ Added to known-issues: [title]"

If .claude/known-issues.md doesn't exist and there's something to record, create the file.

Stage 4: Final verdict

✅ APPROVED — No critical issues ⚠️ APPROVED WITH CAVEATS — Can open PR, yellow items must be resolved ❌ BLOCKED — Critical items must be resolved before PR

Output format

## Stage 1 — Flow Validation
[verdict / "No description provided"]

## Stage 2 — Code Analysis
### Critical 🔴
[list or "None"]
### Important 🟡
[list or "None"]
### Suggestions 🟢
[list or "None"]

## Stage 3 — Known Issues
[new items added / "No new issues recorded"]

## Stage 4 — Verdict
[✅ / ⚠️ / ❌] — justification in 1 line

code-review