complexity

name	complexity
description	This skill should be used when reviewing code for high cyclomatic complexity, deep nesting, or long functions.
user-invocable	false
allowed-tools	Read, Grep, Glob

Complexity Patterns

Domain expertise for code complexity and maintainability analysis. Use alongside devflow:review-methodology for complete complexity reviews.

Iron Law

IF YOU CAN'T UNDERSTAND IT IN 5 MINUTES, IT'S TOO COMPLEX

Every function should be explainable to a colleague in under 5 minutes. If you need a diagram to understand control flow, refactor. If you need comments to explain what (not why), the code is too clever. Simplicity is a feature, complexity is a bug.

---

Complexity Categories

1. Cyclomatic Complexity

High decision path count makes code hard to test and understand.

Violation: Deep nesting (5+ levels)

if (order) {
  if (order.items) {
    for (const item of order.items) {
      if (item.quantity > 0) {
        if (item.product?.inStock) {
          // Buried logic

Solution: Early returns and extraction

function processOrder(order: Order) {
  if (!order?.items) return;
  for (const item of order.items) processItem(item);
}

function processItem(item: OrderItem) {
  if (item.quantity <= 0 || !item.product?.inStock) return;
  // Logic at top level
}

2. Readability Issues

Code that requires mental effort to parse.

Violation: Magic values

if (status === 3) {
  setTimeout(callback, 86400000);
}

Solution: Named constants

const OrderStatus = { COMPLETED: 3 } as const;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

if (status === OrderStatus.COMPLETED) {
  setTimeout(callback, ONE_DAY_MS);
}

3. Maintainability Issues

Code that's expensive to change.

Violation: Long parameter lists

function createUser(name, email, password, role, dept, manager, startDate, salary) { }

Solution: Object parameter

interface CreateUserParams {
  name: string; email: string; password: string;
  role: string; department: string; manager?: string;
  startDate: Date; salary: number;
}
function createUser(params: CreateUserParams) { }

4. Boolean Complexity

Conditions that are hard to reason about.

Violation: Complex boolean expression

if (user.active && !user.deleted && (user.role === 'admin' || user.role === 'moderator') && user.verified && (!user.suspended || user.suspendedUntil < Date.now())) { }

Solution: Extract to named predicate

const canModerate = (user: User): boolean => {
  if (!user.active || user.deleted || !user.verified) return false;
  if (!['admin', 'moderator'].includes(user.role)) return false;
  if (user.suspended && user.suspendedUntil >= Date.now()) return false;
  return true;
};

if (canModerate(user)) { }

5. Reliability Patterns

Operations that risk non-termination or resource exhaustion. See devflow:reliability for full coverage of bounded iteration, assertion density, allocation discipline, and indirection limits. Complexity-relevant: unbounded loops increase cyclomatic complexity and make termination reasoning harder.

---

Extended References

For extended examples and detection techniques:

Reference	Content
references/violations.md	Extended violation examples for all categories
references/patterns.md	Detailed refactoring solutions
references/detection.md	Bash commands and static analysis setup

---

Severity Guidelines

Severity	Criteria
CRITICAL	Functions > 200 lines, complexity > 20, nesting > 6, duplication in 5+ places, unbounded loop on external I/O
HIGH	Functions 50-200 lines, complexity 10-20, nesting 4-6, 5+ boolean conditions, 5+ parameters, retry with no max
MEDIUM	Functions 30-50 lines, complexity 5-10, magic values, minor duplication
LOW	Could be more readable, naming improvements, comments would help

Metrics Quick Reference

Metric	Good	Warning	Critical
Function length	< 30	30-50	> 50
Cyclomatic complexity	< 5	5-10	> 10
Nesting depth	< 3	3-4	> 4
Parameters	< 3	3-5	> 5
File length	< 300	300-500	> 500
Loop bound	explicit	implicit	unbounded