v1-io/v1-complexity

Reduce Cognitive Complexity

Refactor functions to reduce cognitive complexity score while maintaining identical behavior.

Usage

Typical invocations:

• Claude Code: /v1-complexity [file:function]
• Codex: invoke v1-complexity from the skills menu or use $v1-complexity [file:function]

Examples:

/v1-complexity                                    # Analyze current diff
/v1-complexity services/analyst/core/query.py    # Analyze specific file
/v1-complexity query.py:process_result           # Analyze specific function

In Codex, the slash examples below map directly to $v1-complexity ....

Understanding Cognitive Complexity

What increments complexity (+1 each):

• Control flow: if, else if, else, ternary operators
• Loops: for, foreach, while, do while
• Exception handling: catch
• Switch statements: switch, case
• Jump statements: goto, break, continue (labeled)
• Binary logical operators: &&, || in conditions
• Recursive function calls

Nesting multiplier:

• Each nesting level adds +1 to structures nested inside
• Deeper nesting = harder to understand

What's free (no increment):

• Function/method calls (encourages extraction)
• Simple return statements

Target: Keep cognitive complexity under 15 per function

Refactoring Strategies

1. Return Early (Reduce Nesting)

# Before: Complexity 6
def calculate(data):
    if data is not None:  # +1
        total = 0
        for item in data: # +1 +1 (nested)
            if item > 0:  # +1 +2 (nested)
                total += item * 2
        return total

# After: Complexity 4
def calculate(data):
    if data is None:      # +1
        return None
    total = 0
    for item in data:     # +1
        if item > 0:      # +1 +1 (nested)
            total += item * 2
    return total

2. Extract Complex Conditions

# Before: Complexity 5
def process_eligible_users(users):
    for user in users:             # +1
        if ((user.is_active and    # +1 +1 +1 +1
            user.has_profile) or
            user.age > 18):
            user.process()

# After: Complexity 3
def process_eligible_users(users):
    for user in users:             # +1
        if is_eligible_user(user): # +1 +1
            user.process()

def is_eligible_user(user):
    return (user.is_active and user.has_profile) or user.age > 18

3. Break Down Large Functions

Extract logical blocks into separate functions with single responsibilities.

Process

1. Analyze the target function:

   • Current complexity score
   • What's contributing to it
   • Deeply nested structures (2+ levels)
   • Complex boolean conditions

2. Preserve existing tests - understand coverage before changes

3. Refactor using strategies above:

   • Start with early returns to flatten nesting
   • Extract complex conditions into named helpers
   • Break down into smaller functions if still above target
   • Use clear, descriptive names

4. Verify behavior - run existing tests

5. Add tests if needed - for new helper functions with complex logic

Critical Requirements

• ✅ Maintain identical behavior
• ✅ Follow existing code patterns
• ✅ Use descriptive names for extracted functions
• ✅ Keep complexity under 15 per function
• ✅ Run tests to verify correctness