/code-simplification

name: code-simplification
description: Use after implementing features, before claiming a phase is complete, when reviewing AI-generated code, or when code feels overly complex. Also use when you notice repeated patterns across files, a function exceeds 40 lines, nesting exceeds 3 levels, or an abstraction has only one implementation. Covers duplication, dead code, over-engineering, and AI-specific bloat patterns like verbose error handling and redundant type checks.

<!-- TOKEN BUDGET: 400 lines / ~1200 tokens -->

Code Simplification

<activation>

When This Skill Activates

• After all tasks in a phase are complete (before shipping)
• When reviewing code generated by multiple builder agents
• When a file has been touched by 3+ different tasks
• When you notice patterns repeating across files
• Before claiming a phase is production-ready

**The simplifier agent references this skill for systematic cross-task analysis.**

Natural Language Triggers

• "simplify this", "clean up", "too complex", "reduce complexity", "this is bloated"

</activation>

Overview

AI-generated code accumulates complexity. Each task is implemented in isolation by a fresh agent that can't see the full picture. After multiple tasks, duplication creeps in, abstractions multiply, and dead code lingers.

**Core principle:** The simplest code that works correctly is the best code. Complexity is a cost, not a feature.

**This skill applies after implementation, not during.** Don't prematurely optimize -- but don't ship bloat either.

<instructions>

Simplification Process

When reviewing code for simplification:

1. **Identify scope:** What files changed in this phase? (Use git diff) 2. **Scan for duplication:** Look for similar patterns across files 3. **Check complexity:** Flag functions exceeding thresholds 4. **Find dead code:** Look for unused definitions 5. **Spot over-engineering:** Look for abstractions with single implementations 6. **Check AI patterns:** Apply the AI anti-pattern checklist 7. **Prioritize findings:**

• **High:** Clear duplication (3+), dead code, obvious bloat
• **Medium:** Complexity reduction, near-duplicates
• **Low:** Style consistency, minor simplifications

Duplication Detection

What to Look For

**Exact duplicates:** Identical code blocks in different files or functions.

# RED FLAG: Same logic in two places
def validate_user_email(email):
    if not email or "@" not in email:
        raise ValueError("Invalid email")

def validate_contact_email(email):
    if not email or "@" not in email:
        raise ValueError("Invalid email")

**Near duplicates:** Same structure, different details.

# RED FLAG: Parallel structure, only names differ
def create_user(data):
    validate(data)
    user = User(**data)
    db.add(user)
    db.commit()
    return user

def create_project(data):
    validate(data)
    project = Project(**data)
    db.add(project)
    db.commit()
    return project

**Parallel hierarchies:** When adding a new type requires changes in multiple places.

**Copy-paste config:** Same configuration blocks repeated in Docker, Terraform, or CI files.

The Rule of Three

• **2 occurrences:** Note it, but don't extract yet.
• **3 occurrences:** Extract. The pattern is real.
• **1 abstraction serving 1 caller:** Inline it. The abstraction has no value.

Complexity Reduction

Techniques

**Extract method:** When a function does too many things.

# BEFORE: One function doing everything
def process_order(order):
    # validate (10 lines)
    # calculate totals (15 lines)
    # apply discounts (12 lines)
    # save to database (8 lines)
    # send notification (6 lines)

# AFTER: Clear responsibilities
def process_order(order):
    validate_order(order)
    totals = calculate_totals(order)
    totals = apply_discounts(totals, order.customer)
    save_order(order, totals)
    notify_order_placed(order)

**Early returns / guard clauses:** Eliminate deep nesting.

# BEFORE: Nested conditionals
def get_discount(user):
    if user:
        if user.is_premium:
            if user.years > 5:
                return 0.20
            else:
                return 0.10
        else:
            return 0.0
    else:
        return 0.0

# AFTER: Guard clauses
def get_discount(user):
    if not user or not user.is_premium:
        return 0.0
    if user.years > 5:
        return 0.20
    return 0.10

**Replace conditionals with polymorphism:** When type-checking drives behavior.

**Simplify boolean expressions:** Collapse nested boolean logic.

Complexity Thresholds

| Metric | Acceptable | Review | Refactor | |--------|-----------|--------|----------| | Function length | < 20 lines | 20-40 lines | > 40 lines | | Nesting depth | <= 2 levels | 3 levels | > 3 levels | | Parameters | <= 3 | 4-5 | > 5 | | Cyclomatic complexity | <= 5 | 6-10 | > 10 |

Dead Code Identification

What Counts as Dead Code

• **Unused imports** -- imported but never referenced
• **Unused variables** -- assigned but never read
• **Unreachable branches** -- conditions that can never be true
• **Commented-out code** -- if it's needed, it's in git history
• **Unused functions/methods** -- defined but never called
• **Vestigial parameters** -- accepted but never used
• **Feature flags for shipped features** -- the flag is always on

What Does NOT Count

• Public API surface -- may have external callers
• Test utilities -- called only from tests
• Interface implementations -- required by contract
• Error handlers for rare conditions -- needed for robustness

Over-Engineering Indicators

Premature Abstraction

# OVER-ENGINEERED: Abstract factory for one implementation
class NotificationFactory:
    @staticmethod
    def create(type):
        if type == "email":
            return EmailNotifier()
        raise ValueError(f"Unknown: {type}")

# SIMPLE: Just use the thing directly
notifier = EmailNotifier()

**Rule:** If there's on