review-scoring-rubric

Review Scoring Rubric

Complete scoring system for quantified code reviews with weighted categories and severity-based deductions.

Quick Start

Calculate score:

Calculate a score for this codebase using the 10-category weighted rubric.

Specific category audit:

Analyze the Testing category and calculate its weighted contribution to the score.

The Formula

Final Score = 10 - Total Weighted Deductions

Where:
Total Weighted Deductions = SUM(Category Deduction * Category Weight)
Category Deduction = SUM(Issue Points * Severity Multiplier)

Maximum Deduction per Category: 10 points (caps at 0 for category)

---

Severity Multipliers

Severity	Multiplier	Description	Example Issues
Critical	2.0x	Active danger, data loss, security holes	SQL injection, RCE, hardcoded secrets
Major	1.5x	Significant problems, high bug potential	God classes, no tests, N+1 queries
Minor	1.0x	Code smells, maintainability issues	Long functions, magic numbers
Nitpick	0.5x	Style, preferences, minor polish	Naming conventions, formatting

---

Category Weights

Category	Weight	Focus Areas
Organization	12%	File structure, module boundaries, separation of concerns
Naming	10%	Variables, functions, classes, constants clarity
Error Handling	12%	Try/catch, validation, error propagation, recovery
Testing	12%	Coverage, test quality, edge cases, mocking
Performance	10%	Efficiency, N+1 queries, memory leaks, scalability
Security	12%	Input validation, auth, secrets, injection
Documentation	8%	Useful comments, API docs, README
SOLID/DRY	10%	SRP, OCP, LSP, ISP, DIP, no duplication
Dependencies	6%	Minimal deps, no circular refs, versions
Maintainability	8%	Complexity, readability, nesting depth
Total	100%

---

Category 1: Organization (12%)

What to Evaluate

• File and folder structure
• Module boundaries and cohesion
• Separation of concerns
• Entry points and flow clarity

Deduction Reference

Issue	Base Points	Severity
God file (500+ lines)	1.5	Critical
God file (300-500 lines)	1.0	Major
No clear folder structure	1.0	Major
Mixed concerns in file	0.75	Major
Files in wrong directory	0.5	Minor
Inconsistent file naming	0.5	Minor
Too many files in one folder (20+)	0.5	Minor
Unclear entry point	0.25	Minor

Detection Commands

# Files over 300 lines
find src -name "*.ts" -exec wc -l {} \; | awk '$1 > 300 {print}'

# File count per directory
find src -type d -exec sh -c 'echo -n "{}: "; ls -1 "{}" 2>/dev/null | wc -l' \;

# Files in src root (should be minimal)
ls -la src/*.ts 2>/dev/null | wc -l

Grade Thresholds

Grade	Criteria
A	Clean feature-based structure, clear boundaries, <300 line files
B	Mostly organized, few large files, clear flow
C	Some structure issues, mixed concerns
D	Disorganized, many large files, unclear flow
F	No structure, god files everywhere

---

Category 2: Naming (10%)

What to Evaluate

• Variable name clarity
• Function name accuracy
• Class name appropriateness
• Constant documentation

Deduction Reference

Issue	Base Points	Severity
Misleading names	1.0	Major
Single-letter variables (non-loop)	0.75	Major
Generic names (data, temp, result, item)	0.5	Minor
Inconsistent casing style	0.5	Minor
Magic numbers without constants	0.5	Minor
Abbreviated names (unclear)	0.25	Minor
Boolean without is/has/can prefix	0.25	Nitpick

Detection Commands

# Single letter variables
grep -rn "const [a-z] =\|let [a-z] =\|var [a-z] =" src/

# Generic names
grep -rn "const data =\|let data =\|const result =\|let temp =" src/

# Magic numbers
grep -rn "[^0-9\.][0-9]\{2,\}[^0-9\.]" src/ | grep -v "test\|spec"

---

Category 3: Error Handling (12%)

What to Evaluate

• Try/catch placement
• Error messages quality
• Error recovery strategies
• Validation completeness

Deduction Reference

Issue	Base Points	Severity
No error handling in critical path	2.0	Critical
Empty catch blocks	1.5	Critical
Catching and ignoring	1.5	Critical
Generic error messages	0.75	Major
No input validation	0.75	Major
console.error without proper handling	0.5	Minor
Missing error types/classes	0.5	Minor
Inconsistent error patterns	0.25	Minor

Detection Commands

# Empty catch blocks
grep -rn "catch.*{\s*}" src/
grep -rA2 "catch" src/ | grep -B1 "^\s*}"

# console.error without throw
grep -rn "console.error" src/ | wc -l

# Missing try/catch around async
grep -rn "await" src/ | head -20

---

Category 4: Testing (12%)

What to Evaluate

• Test coverage percentage
• Test quality (not just quantity)
• Edge case coverage
• Mock/stub appropriateness

Deduction Reference

Issue	Base Points	Severity
0% test coverage	3.0	Critical
No tests for critical paths	2.0	Critical
<50% coverage	1.5	Major
50-70% coverage	1.0	Major
Tests that don't assert	1.0	Major
No edge case tests	0.75	Major
70-80% coverage	0.5	Minor
Missing integration tests	0.5	Minor
Flaky tests	0.5	Minor

Detection Commands

# Test file count
find . -name "*.test.*" -o -name "*.spec.*" | wc -l

# Source file count (for ratio)
find src -name "*.ts" | wc -l

# Coverage report
npm test -- --coverage 2>/dev/null
npx jest --coverage 2>/dev/null

Coverage Thresholds

Coverage	Grade	Deduction
90%+	A	0
80-89%	B	0.5
70-79%	C	1.0
50-69%	D	1.5
<50%	F	2.0+

---

Category 5: Performance (10%)

What to Evaluate

• Algorithm efficiency
• Database query patterns
• Memory management
• Async/blocking operations

Deduction Reference

Issue	Base Points	Severity
N+1 query in hot path	1.5	Critical
Memory leak pattern	1.5	Critical
Blocking operation in async	1.0	Major
O(n^2) in hot path	1.0	Major
Missing pagination	0.75	Major
No caching strategy	0.5	Minor
Sequential instead of parallel	0.5	Minor
Missing indexes	0.5	Minor

Detection Commands

# N+1 patterns (loop with query)
grep -rn "for.*await\|forEach.*await" src/
grep -rn "\.findAll\|\.findMany" src/ | head -10

# Sync operations in async
grep -rn "readFileSync\|writeFileSync" src/
grep -rn "execSync" src/

See references/performance-detection.md for detailed patterns.

---

Category 6: Security (12%)

What to Evaluate

• Input validation
• Authentication/authorization
• Secrets management
• Injection prevention

Deduction Reference

Issue	Base Points	Severity
SQL injection	2.0	Critical
Command injection	2.0	Critical
Hardcoded secrets	2.0	Critical
XSS vulnerability	1.5	Critical
Missing auth on endpoint	1.5	Critical
IDOR vulnerability	1.5	High
No input validation	1.0	Major
Weak cryptography	0.75	Major
Missing security headers	0.5	Minor
Verbose error messages	0.25	Minor

Detection Commands

# Injection patterns
grep -rn "\`SELECT.*\${" src/
grep -rn "exec\|eval" src/

# Secrets
grep -rn "password.*=.*['\"]" src/
grep -rn "api_key.*=.*['\"]" src/

# npm audit
npm audit --json 2>/dev/null | jq '.metadata.vulnerabilities'

See security-audit-checklist skill for comprehensive coverage.

---

Category 7: Documentation (8%)

What to Evaluate

• README completeness
• API documentation
• Code comments (why, not what)
• Type definitions

Deduction Reference

Issue	Base Points	Severity
No README	1.0	Major
No API documentation	0.75	Major
Missing setup instructions	0.5	Minor
Outdated documentation	0.5	Minor
Comments explaining "what"	0.25	Nitpick
TODO comments without issues	0.25	Nitpick
Missing JSDoc on public API	0.25	Nitpick

Detection Commands

# Check README exists
ls README.md 2>/dev/null

# Count TODO comments
grep -rn "TODO\|FIXME\|XXX\|HACK" src/ | wc -l

# Check for JSDoc
grep -rn "/\*\*" src/ | wc -l

---

Category 8: SOLID/DRY (10%)

What to Evaluate

• Single Responsibility adherence
• Open/Closed design
• Liskov Substitution
• Interface Segregation
• Dependency Inversion
• Code duplication

Deduction Reference

Issue	Base Points	Severity
God class (1000+ lines)	2.0	Critical
SRP violation (multi-domain class)	1.0	Major
Switch on type (multiple places)	0.75	Major
OCP violation (modify to extend)	0.75	Major
LSP violation (broken substitution)	0.75	Major
Large interface (10+ methods)	0.5	Minor
Concrete dependencies	0.5	Minor
Duplicated code blocks	0.5	Minor

Detection Commands

# Duplicate code
npx jscpd src/ --min-lines 10

# Large classes
grep -A 500 "^class" src/**/*.ts | head -100

# Switch statements on type
grep -rn "switch.*type\|switch.*kind" src/

See code-smell-detector skill for comprehensive patterns.

---

Category 9: Dependencies (6%)

What to Evaluate

• Dependency count
• Circular dependencies
• Version management
• Security vulnerabilities

Deduction Reference

Issue	Base Points	Severity
Critical CVE in dependency	2.0	Critical
Circular dependencies	1.0	Major
Excessive dependencies (50+)	0.75	Major
High CVE in dependency	0.5	Major
Outdated major versions	0.5	Minor
No lockfile	0.5	Minor
Unused dependencies	0.25	Minor

Detection Commands

# Dependency count
cat package.json | jq '.dependencies | length'

# Circular dependencies
npx madge --circular src/

# Security audit
npm audit --json

# Unused dependencies
npx depcheck

# Outdated packages
npm outdated

---

Category 10: Maintainability (8%)

What to Evaluate

• Cyclomatic complexity
• Nesting depth
• Code readability
• Cognitive load

Deduction Reference

Issue	Base Points	Severity
Function complexity >30	1.5	Critical
Function complexity 20-30	1.0	Major
Nesting depth 5+	1.0	Major
Function complexity 15-20	0.5	Minor
Function >100 lines	0.5	Minor
Nesting depth 4	0.25	Minor
any types everywhere	0.5	Minor
Inconsistent formatting	0.25	Nitpick

Detection Commands

# Complexity analysis
npx escomplex src/ --format json | jq '.aggregate.cyclomatic'

# TypeScript any usage
grep -rn ": any\|as any" src/ | wc -l

# Type coverage
npx type-coverage --detail 2>/dev/null

---

Score Calculation Example

Category: Security (Weight: 12%)

Issues Found:
1. SQL Injection (src/api/users.ts:45)
   - Base: 2.0, Severity: Critical (2.0x)
   - Deduction: 2.0 * 2.0 = 4.0

2. Hardcoded API key (src/config.ts:12)
   - Base: 2.0, Severity: Critical (2.0x)
   - Deduction: 2.0 * 2.0 = 4.0

3. Missing input validation (5 endpoints)
   - Base: 1.0, Severity: Major (1.5x)
   - Deduction: 1.0 * 1.5 = 1.5

Category Raw Deduction: 4.0 + 4.0 + 1.5 = 9.5 (capped at 10)
Category Raw Score: 10 - 9.5 = 0.5/10
Weighted Contribution: 0.5 * 0.12 = 0.06 (out of 1.20 max)
Grade: F

---

Score Interpretation

Score	Verdict	Reality Check
10	Exemplary	You actually did everything right. Rare.
9	Excellent	Minor polish. Ship it.
8	Very Good	Few small fixes. Solid work.
7	Good	Acceptable. Some cleanup needed.
6	Satisfactory	Works but rough. Needs attention.
5	Adequate	Barely meets the bar. Clear problems.
4	Below Average	Significant issues. Risky to deploy.
3	Poor	Major rework needed. Architectural problems.
2	Very Poor	Fundamental issues. Barely functional.
1	Critical	Do not deploy. Security holes. Will crash.

---

Report Template

## Score Breakdown

| Category | Weight | Raw Score | Deductions | Weighted | Grade |
|----------|--------|-----------|------------|----------|-------|
| Organization | 12% | X.X/10 | -X.X | X.XX/1.20 | {A-F} |
| Naming | 10% | X.X/10 | -X.X | X.XX/1.00 | {A-F} |
| Error Handling | 12% | X.X/10 | -X.X | X.XX/1.20 | {A-F} |
| Testing | 12% | X.X/10 | -X.X | X.XX/1.20 | {A-F} |
| Performance | 10% | X.X/10 | -X.X | X.XX/1.00 | {A-F} |
| Security | 12% | X.X/10 | -X.X | X.XX/1.20 | {A-F} |
| Documentation | 8% | X.X/10 | -X.X | X.XX/0.80 | {A-F} |
| SOLID/DRY | 10% | X.X/10 | -X.X | X.XX/1.00 | {A-F} |
| Dependencies | 6% | X.X/10 | -X.X | X.XX/0.60 | {A-F} |
| Maintainability | 8% | X.X/10 | -X.X | X.XX/0.80 | {A-F} |
| **TOTAL** | **100%** | | **-X.X** | **X.XX/10.00** | |

### Grade Scale
- A: 9.0-10.0 (Excellent)
- B: 7.0-8.9 (Good)
- C: 5.0-6.9 (Acceptable)
- D: 3.0-4.9 (Poor)
- F: 0.0-2.9 (Failing)

Reference Files

• references/performance-detection.md - Performance issue detection patterns
• references/quick-reference-card.md - One-page scoring summary