---
type: skill
domain: architecture
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# COMPLEXITY_CRUSHER
> **ROLE:** SIMPLICITY ARCHITECT
> **TRIGGER:** "SIMPLIFY"

## Core Mandate
Simple is better than complex. Complex is better than complicated. If two solutions work, pick the one with fewer moving parts.

## Step-by-Step Protocol
1. **Brain check**: `python Autonomic_System/Utilities/Tools/brain_query.py --query "complexity issues in <module>"`
2. **Score the code**: Measure cyclomatic complexity, nesting depth, function length, and file length against thresholds below.
3. **Apply early returns**: Replace nested if/else chains with guard clauses that return early. Target: max 2 levels of nesting.
4. **Extract or delete**: Functions >50 lines get split. "Just-in-case" code with no callers gets deleted. Middle-man functions that only forward calls get inlined.
5. **Verify and save**: Run `ruff check --select C901` to confirm complexity <10. Save learnings via `pulse_save.py`.

## Complexity Scoring Rules
| Metric | Green | Yellow (refactor soon) | Red (refactor NOW) |
|---|---|---|---|
| Cyclomatic complexity | 1-5 | 6-10 | >10 |
| Nesting depth | 1-2 | 3 | 4+ |
| Function length | 1-25 lines | 26-50 lines | >50 lines |
| File length | 1-200 lines | 201-400 lines | >400 lines |
| Parameters per function | 1-3 | 4-5 | 6+ |
| Return statements | 1-2 | 3-4 | 5+ |

## Good Example: Flatten Nested Logic
```python
# BAD: 4 levels of nesting
def process_task(task):
    if task:
        if task.get("status") == "open":
            if task.get("tier") in VALID_TIERS:
                if can_claim(task):
                    return claim(task)
    return None

# GOOD: Early returns, max 1 level of nesting
def process_task(task):
    if not task:
        return None
    if task.get("status") != "open":
        return None
    if task.get("tier") not in VALID_TIERS:
        return None
    if not can_claim(task):
        return None
    return claim(task)
```

## Refactoring Thresholds
- **Complexity >10**: Mandatory split into sub-functions before merge.
- **File >400 lines**: Decompose into 2+ modules with clear boundaries.
- **6+ parameters**: Introduce a config dict or dataclass.
- **Duplicate code >3 lines appearing 2+ times**: Extract to shared function.

## Anti-Patterns
- **"Clever" one-liners**: A 200-char list comprehension is worse than a 5-line loop. Optimize for reading, not writing.
- **Premature abstraction**: Don't create a base class for one implementation. Wait for the Rule of Three.
- **Middle-man functions**: `def get_data(): return _get_data()` adds indirection with zero value. Inline it.

## Tools to Use
- `ruff check --select C901 <path>` -- measure cyclomatic complexity
- `brain_query.py --query "complexity in <module>"` -- check prior refactoring lessons
- `pulse_relay.py --tasks "Refactor <module>:architecture:standard"` -- delegate refactors
- `Hippocampus/Patterns/` -- check for known complexity offenders

## Verification Checklist
- [ ] All functions have cyclomatic complexity <10 (`ruff --select C901`)
- [ ] No function exceeds 50 lines
- [ ] No nesting deeper than 3 levels
- [ ] No file exceeds 400 lines
- [ ] No function takes more than 5 parameters
- [ ] All duplicate code blocks extracted to shared functions
