Complexity Review Skill

Purpose

Provides automated complexity analysis commands and manual detection patterns for identifying hard-to-maintain code. Use this as a reference for WHAT to check and HOW to detect complexity issues—not for output formatting or workflow.

Automated Complexity Analysis

Run Lizard complexity analyzer:

bash ~/.claude/plugins/marketplaces/claude-configs/review/scripts/review-complexity.sh

Returns:

• Functions with cyclomatic complexity >= 15
• NLOC (Non-comment Lines Of Code)
• CCN (Cyclomatic Complexity Number)
• Token count, parameter count, function length
• Format: NLOC CCN Token Parameter Length Location

Example output:

45 18 234 5 50 src/utils.ts:calculateTotal

Complexity Metrics Reference

Cyclomatic Complexity (CCN)

Counts independent paths through code based on decision points: if/else, switch, loops, ternary operators, logical operators (&&, ||)

Thresholds:

• 1-5: Simple, easy to test
• 6-10: Moderate, acceptable
• 11-15: Complex, consider refactoring
• 16+: High risk, refactor recommended

Function Length (NLOC)

Non-comment lines in a function.

Thresholds:

• 1-20: Good
• 21-50: Acceptable
• 51-100: Consider splitting
• 100+: Too long, refactor

Parameter Count

Thresholds:

• 0-3: Good
• 4-5: Acceptable
• 6+: Too many, use object parameter

Nesting Depth

Levels of indentation.

Thresholds:

• 1-2: Good
• 3: Acceptable
• 4+: Too deep, simplify

Manual Detection Patterns

When automated tools unavailable or for deeper analysis, use Read/Grep to detect:

Multiple Responsibilities

# Find functions with multiple comment sections

grep -A 50 "function\|const._=._=>" <file> | grep -c "^[[:space:]]\*\/\/"

Look for: Functions with validation + transformation + persistence + notification in one place

Deep Nesting

# Find lines with >3 levels of indentation (12+ spaces)

grep -n "^[[:space:]]{12,}" <file>

Look for: Nested if statements >3 levels deep

Long Conditional Chains

# Find files with many else-if statements

grep -c "else if" <file>

Look for: Functions with >5 else-if branches

High Parameter Count

# Find function declarations

grep -n "function._([^)]_,[^)]_,[^)]_,[^)]_,[^)]_," <file>

Look for: Functions with >5 parameters

Mixed Abstraction Levels

Use Read to identify functions that mix:

• High-level orchestration with low-level string manipulation
• Business logic with infrastructure concerns
• Domain logic with presentation logic

Cognitive Load Indicators

Magic Numbers:

grep -n "[^a-zA-Z_][0-9]{2,}[^a-zA-Z_]" <file>

Look for: Unexplained numeric literals

Excessive Comments:

# Count comment density

total_lines=$(wc -l < <file>)
comment_lines=$(grep -c "^[[:space:]]\*\/\/" <file>)

Look for: Comment ratio >20% (indicates unclear code)

Side Effects:

grep -n "this\.\|global\.\|window\.\|process\.env" <file>

Look for: Functions accessing external state

Complexity Sources to Identify

When reviewing flagged functions, identify specific causes:

Pattern	Detection Method	Example
Multiple Responsibilities	Function does >1 distinct task	Validation + transformation + persistence
Deep Nesting	Indentation >3 levels	if > if > if > if
Long Conditional Chains	>5 else-if branches	type === 'A' || type === 'B' || ...
Mixed Abstraction Levels	High + low level code mixed	orchestration + string manipulation
Magic Numbers	Unexplained literals	if (status === 42)
Excessive Comments	Comment ratio >20%	Every line needs explanation
Side Effects	Modifies external state	Accesses globals, mutates inputs
High Parameter Count	>5 parameters	function(a, b, c, d, e, f)

Refactoring Patterns

Suggest these patterns based on complexity source:

Extract Method

When: Function >50 lines or multiple responsibilities Pattern:

// Before: 40 lines doing validation + transformation + persistence
function process(data) {
  /_ 40 lines _/;
}

// After: 3 focused functions
function process(data) {
  validate(data);
  const transformed = transform(data);
  persist(transformed);
}

Guard Clauses

When: Deep nesting >3 levels Pattern:

// Before: Nested ifs
if (valid) {
  if (ready) {
    if (allowed) {
      /_ logic _/;
    }
  }
}

// After: Early returns
if (!valid) return;
if (!ready) return;
if (!allowed) return;
/_ logic _/;

Replace Conditional with Lookup

When: >5 else-if branches Pattern:

// Before: Long if-else chain
if (type === 'A') {
  doA();
} else if (type === 'B') {
  doB();
}

// After: Lookup table
const strategies = { A: doA, B: doB };
strategies[type]();

Parameter Object

When: >5 parameters Pattern:

// Before: Many parameters
function create(name, email, age, address, phone, city) {}

// After: Object parameter
function create(userData: UserData) {}

Extract Variable

When: Complex conditionals or magic numbers Pattern:

// Before: Unclear condition
if (user.age > 18 && user.status === 'active' && user.balance > 100) {
}

// After: Named boolean
const isEligibleUser = user.age > 18 && user.status === 'active' && user.balance > 100;
if (isEligibleUser) {
}

Severity Mapping

Use these criteria when classifying findings:

Metric	Severity	Rationale
CCN >= 25	critical	Extremely high risk, untestable
CCN 20-24	high	High risk, difficult to maintain
CCN 15-19	high	Complex, refactor recommended
NLOC > 100	high	Too long, hard to understand
Nesting depth > 4	high	Hard to follow logic
CCN 11-14	medium	Moderate complexity
NLOC 51-100	medium	Consider splitting
Parameters > 5	medium	Hard to use correctly
Nesting depth 4	medium	Approaching complexity limit
CCN 6-10	nitpick	Acceptable but monitor
NLOC 21-50	nitpick	Acceptable length
Parameters 4-5	nitpick	Consider object parameter

Red Flags

Watch for these warning signs when reviewing complex functions:

• Needs comments to explain logic - Code should be self-documenting
• Hard to write unit tests - High complexity makes testing difficult
• Frequent source of bugs - Check git history for bug fixes
• Developers avoid modifying - Ask team about "scary" functions
• Takes >5 minutes to understand - Cognitive load too high
• Mixed abstraction levels - Doing too many things

Analysis Priority

1. Run Lizard script first (if available)
2. Parse Lizard output for functions with CCN >= 15
3. Read flagged functions using Read tool
4. Identify complexity sources using patterns above
5. Apply manual detection patterns if Lizard unavailable
6. Cross-reference with git history (frequent changes = high-risk complexity)
7. Suggest specific refactoring patterns based on complexity source

Integration Notes

• This skill provides detection methods and refactoring patterns only
• Output formatting is handled by the calling agent
• Severity classification should align with agent's schema
• Do NOT include effort estimates (handled by agent if needed)
• Focus on identifying complexity, not prescribing workflow