code-review

Code Review

Perform a thorough senior-level code review on recent changes. Focus human review on complex logic, architecture, and edge cases. Delegate style enforcement to automated tools.

Related Skills:

• kavak-documentation - Query for Kavak-specific patterns, logging/metrics standards, GitLab CI templates
• Use kavak-platform/platform_docs_search MCP tool to verify Kavak best practices when reviewing

Quick Start

# 1. Get review range
BASE_SHA=$(git rev-parse HEAD~1)  # or: git merge-base main HEAD
HEAD_SHA=$(git rev-parse HEAD)

# 2. See what changed
git diff --stat $BASE_SHA..$HEAD_SHA
git diff --name-only $BASE_SHA..$HEAD_SHA --diff-filter=ACMR

# 3. After review, run quality gates (detect project type)

Quality gate commands by language:

Language	Lint	Build	Test
Go	golangci-lint run	go build ./...	go test ./...
Node/TS	npm run lint	npm run build	npm test
Python	ruff check .	python -m py_compile	pytest
Java	./mvnw checkstyle:check	./mvnw compile	./mvnw test

When to Review

This workflow applies to both self-reviews and peer reviews.

Mandatory: after completing a task, after implementing a feature, before merging.

Valuable: when stuck (fresh perspective), before refactoring (baseline), after fixing complex bugs.

Review Mindset

• Thorough, not rushed - Read all related code before concluding
• Evidence-based - Trace execution paths, don't assume bugs exist
• Fix, don't just flag - Identify issues AND resolve them
• Small scope - Review <400 lines at a time for effectiveness

Workflow

1. Scope the Diff

Identify all changed files:

git diff --name-only HEAD~1 --diff-filter=ACMR

For each file in the list, skip any that produces no actual diff hunks.

2. Understand Intent & Requirements

Before reviewing code, understand what it should do:

• Original task/issue: What was requested?
• Product impact: What does this deliver for users?
• Acceptance criteria: What defines "done"?

Ask: "Does the implementation satisfy the requirements?"

3. Review Each File

For each changed file and each diff hunk, evaluate in context of the existing codebase.

MANDATORY: Before flagging Critical/Major, trace the complete execution path end-to-end. Confirm no defensive code prevents the issue. Consider error paths, cancellation, and edge cases.

4. Review Categories

Focus on: architecture (fits patterns, avoids coupling), correctness (edge cases, error handling), security (input validation, secrets, OWASP), performance (N+1 queries, memory), logging/metrics (cardinality explosions). Delegate style to linters.

Full checklist with all 11 categories: references/checklist.md Logging and metrics standards: references/logging-metrics-review.md

5. Check Project Rules

MANDATORY: Check and enforce rules from:

• .claude/CLAUDE.md or CLAUDE.md (root)
• .cursor/rules/ folder
• AGENTS.md
• Follow ALL patterns and conventions defined there

6. Report & Fix Issues

For each validated issue:

• File: <path>:<line-range>
• Issue: One-line summary
• Fix: Concise suggested change

Severity levels:

• Critical (P0): Security vulnerabilities, data loss, crashes
• Major (P1): Significant bugs, performance issues, architectural violations
• Minor (P2): Code style, minor improvements
• Enhancement (P3): Nice-to-have improvements

MANDATORY: Fix all issues immediately after identifying them.

1. Start with highest priority (Critical → Major → Minor)
2. For each issue:
   • Fix the code
   • Verify fix doesn't break anything
   • CHECKPOINT COMMIT: git add -A && git commit -m "fix: brief description"
3. Continue until ALL issues are resolved

7. Run Quality Gates

After all issues are fixed, run lint → build → test for project type (see Quick Start table).

If any gate fails, fix immediately and commit the fix.

8. Final Report

Provide structured output:

### Strengths

[What's well done - be specific with file:line references]

### Issues Found & Fixed

- **Critical**: [count] - [brief list]
- **Major**: [count] - [brief list]
- **Minor**: [count] - [brief list]

### Quality Gates

- Lint: ✓/✗
- Typecheck: ✓/✗
- Build: ✓/✗
- Tests: ✓/✗

### Assessment

**Ready to proceed?** [Yes / Yes with notes / No - needs fixes]
**Reasoning:** [1-2 sentence technical assessment]

If no issues: "Code review complete. No issues found. All quality gates pass. Ready to proceed."

References

Reference	Purpose
references/checklist.md	Detailed review checklist
references/severity-guide.md	How to classify issue severity
references/common-issues.md	Common issues (TypeScript/Node)
references/common-issues-go.md	Common issues (Go)
references/security-owasp.md	OWASP Top 10 security checklist
references/feedback-guide.md	How to give constructive feedback
references/logging-metrics-review.md	Logging format and metrics cardinality standards
references/self-review-workflow.md	Automated self-review during development

Best Practices

1. No assumptions - Read ALL related code before flagging issues
2. Fix immediately - Don't just report, fix and commit
3. Checkpoint commits - Commit each fix separately for easy rollback
4. Verify first - Trace execution paths before claiming bugs exist
5. Project rules priority - Always check .cursor/rules/ and AGENTS.md
6. Be timely - Review promptly to avoid blocking teammates
7. Limit scope - Review <400 lines at a time for effectiveness

Principle: Review → Fix → Verify → Commit. A review that only identifies problems without fixing them is incomplete.