Cognitive Load Reducer

The Problem

Your team inherited a 200K-line codebase. The processOrder() function is 180 lines long, has 4 levels of nesting, 12 variables in scope, and 6 boolean flags passed between helper functions. Every developer who touches it needs 30 minutes just to understand the control flow. PRs that modify this function consistently introduce regressions because no one can hold the full branching logic in their head. The code works. But it's burning 15 minutes of cognitive overhead per developer per interaction — and that adds up to thousands of hours per year.

What You Get

• Measure cognitive load per function — count lines of code, nesting depth, branching points, variables in scope, and cyclomatic complexity, flagging functions that exceed thresholds (40+ lines, 3+ nesting depth, 8+ branches, 7+ variables)
• Classify complexity into six patterns — Deep Nesting, God Function, Flag Parade, Excessive Mutation, Arrow Anti-Pattern (callback pyramids), and Boolean Soup — each with a targeted transformation strategy
• Apply guard clause extraction — convert nested if/else blocks into early returns, making preconditions explicit and flattening the main logic path
• Split god functions — extract validation, formatting, persistence, and other concerns into named functions with clear single responsibilities, each under 20 lines
• Extract boolean conditions — replace if (user.role === 'admin' || user.role === 'mod') && doc.status !== 'archived' && ... with named booleans like isPrivilegedUser, isNotArchived, hasAccess
• Verify behavioral equivalence — run existing tests after each transformation, measure re-measured complexity, and produce diffs that show only structural changes (no logic, no whitespace, no unrelated renames)

Why This Beats Prompting It Yourself

Telling an agent "simplify this function" produces one of two outcomes: it extracts trivial one-liners into unnecessary functions (making the code harder to navigate), or it rewrites the logic entirely (introducing subtle bugs). This skill applies a three-pass methodology — Scan (measure), Diagnose (classify pattern), Simplify (apply specific transformation) — with guardrails that prevent over-simplification and require test verification after every change. The agent stops simplifying when the function is under threshold, not when it runs out of ideas.

Example Session

You: "Reduce cognitive load in src/services/orderProcessing.ts"

Agent:

COGNITIVE LOAD AUDIT: ORDERPROCESSING.TS
════════════════════════════════════════

FLAGGED FUNCTIONS
─────────────────
Function           Lines  Nesting  Branches  Variables  Complexity Score
─────────────────  ─────  ───────  ────────  ─────────  ────────────────
processOrder()     180    4        12        14         HIGH
validatePayment()  65     3        8         9          MEDIUM
formatInvoice()    45     2        4         6          LOW

PATTERN CLASSIFICATION: PROCESSORDER()
──────────────────────────────────────
- Deep Nesting (4 levels): preconditions nested inside each other
- God Function: validation + business logic + persistence + notification
- Flag Parade: isRefundable, hasInsurance, isWholesale passed as 5+ flags

TRANSFORMATION: GUARD CLAUSE EXTRACTION
───────────────────────────────────────
Before (4-level nesting):

Before (4-level nesting):

def process_order(order, user, inventory):
    if order and user:
        if user.is_active:
            if order.total > 0:
                if inventory.check(order.items): ...

After (flat preconditions):

def process_order(order, user, inventory):
    if not order or not user or not user.is_active:
        return None
    if order.total <= 0 or not inventory.check(order.items):
        return None
    ...