code-review

```bash

# 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 |

Mandatory triggers:

• After completing each task in multi-step development
• After implementing a major feature
• Before merging to main branch

Valuable triggers:

• When stuck (fresh perspective on own code)
• Before refactoring (baseline check)
• After fixing complex bugs

• 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

1. Scope the Diff

Identify all changed files:

```bash

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: Trace Complete Execution Before Flagging Critical/Major

Before classifying any issue as Critical or Major, you MUST:

1. Read the complete code path - not just the suspicious line
2. Trace what actually happens - follow execution from start to end
3. Verify the issue exists - confirm there is no defensive code preventing it
4. Consider all scenarios - including error paths, cancellation, edge cases

4. Review Categories

| Category | What to Check |

| -------------------------------- | ------------------------------------------------------- |

| Design & Architecture | Fits system patterns, avoids coupling, clear separation |

| Complexity & Maintainability | Flat control flow, low complexity, DRY, no dead code |

| Functionality & Correctness | Valid/invalid inputs handled, edge cases covered |

| Readability & Naming | Intent-revealing names, comments explain WHY |

| Best Practices | Language/framework idioms, SOLID principles |

| Test Coverage | Success + failure paths tested |

| Standardization | Style guide conformance, zero new lint warnings |

| Security | Input validation, secrets management, OWASP Top 10 |

| Performance | No N+1 queries, efficient I/O, no memory leaks |

| Logging | State machine pattern, proper tense, actionable context |

| Metrics | No cardinality explosions, proper naming, documented |

Automation tip: Delegate style/formatting to linters (ESLint, Prettier). Focus human review on logic, architecture, and edge cases.

4.1 Logging Review

| Check | ✓ Good | ✗ Bad |

|-------|--------|-------|

| Length | 50-200 chars | >200 (truncation) |

| Multiline | Single line | Multiple lines |

| Start | "Syncing orders" (progressive) | "Sync orders" |

| End OK | "Orders synced" (past) | "Syncing complete" |

| End Fail | "Failed to sync orders" | "Error" |

| Context | "DB timeout after 30s" | "Database error" |

4.2 Metrics Review

| Check | ✓ Good | ✗ Bad (CRITICAL) |

|-------|--------|------------------|

| Labels | status=2xx, method=GET | user_id, order_id |

| Naming | api.request.total | apiRequestTotal |

| Type | Counter (events), Histogram (latency) | Gauge for everything |

CRITICAL: High-cardinality labels (user_id, request_id, timestamp) cause monitoring system crashes.

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: :
• 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"

1. 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:

```markdown

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."

| 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/self-review-workflow.md | Automated self-review during development |

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.