code-simplification

<!-- 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:
8. High: Clear duplication (3+), dead code, obvious bloat
9. Medium: Complexity reduction, near-duplicates
10. 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 only one implementation, don't create an abstraction. Add it when the second implementation arrives.

Unnecessary Indirection

# OVER-ENGINEERED: Service wrapping a service
class UserService:
    def get_user(self, id):
        return self.repository.get_user(id)  # Just passes through

# SIMPLE: Use the repository directly where needed
user = repository.get_user(id)

Configuration for One Value

# OVER-ENGINEERED
MAX_RETRIES = config.get("max_retries", 3)

# SIMPLE (if this is the only place retries happen)
MAX_RETRIES = 3

Rule: Make it configurable when a second consumer needs a different value, not before.

AI-Specific Anti-Patterns

AI code generators commonly produce these patterns. Watch for them:

Verbose Error Handling

# AI BLOAT: Every function has identical error handling
def get_user(id):
    try:
        user = db.query(User).get(id)
        if user is None:
            raise ValueError(f"User {id} not found")
        return user
    except ValueError:
        raise
    except Exception as e:
        logger.error(f"Error getting user: {e}")
        raise RuntimeError(f"Failed to get user {id}") from e

# SIMPLER: Let exceptions propagate naturally
def get_user(id):
    user = db.query(User).get(id)
    if user is None:
        raise ValueError(f"User {id} not found")
    return user

Redundant Type Checks

# AI BLOAT: Checking types that can't be wrong
def process(items: list[str]) -> None:
    if not isinstance(items, list):
        raise TypeError("Expected list")
    for item in items:
        if not isinstance(item, str):
            raise TypeError("Expected str")
        # actual logic...

# SIMPLER: Trust the type system
def process(items: list[str]) -> None:
    for item in items:
        # actual logic...

Over-Defensive Coding

# AI BLOAT: Null checks where nulls can't happen
user = get_authenticated_user()  # Already validated by middleware
if user is not None and user.id is not None:  # Impossible to be None
    process(user)

# SIMPLER: Trust your system boundaries
user = get_authenticated_user()
process(user)

Unnecessary Wrapper Functions

# AI BLOAT: Wrapping standard library
def read_json_file(path):
    with open(path) as f:
        return json.load(f)

# Used exactly once -- just inline it
with open(config_path) as f:
    config = json.load(f)

Shell/Bash AI Anti-Patterns

# AI BLOAT: Excessive logging in every function
m