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

Category Weights

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

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

Category 2: Naming (10%)

What to Evaluate

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

Deduction Reference

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

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

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

Category 5: Performance (10%)

What to Evaluate

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

Deduction Reference

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

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

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

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

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

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

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