code-simplification

Code Simplification

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"

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.

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")