code-simplification

<!-- TOKEN BUDGET: 370 lines / ~1110 tokens -->

# Code Simplification

## 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.

## When to Use

**Always:**
- 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.**

## 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 abstrac