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:

Identify scope: What files changed in this phase? (Use git diff)
Scan for duplication: Look for similar patterns across files
Check complexity: Flag functions exceeding thresholds
Find dead code: Look for unused definitions
Spot over-engineering: Look for abstractions with single implementations
Check AI patterns: Apply the AI anti-pattern checklist
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 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)

Example: Full Simplification Finding

Finding: Three near-identical validate_request_body() functions in routes/users.py, routes/projects.py, and routes/teams.py.

Before (in each file):

def validate_request_body(body, required_fields):
    if not body:
        raise HTTPError(400, "Request body required")
    for field in required_fields:
        if field not in body:
            raise HTTPError(400, f"Missing field: {field}")

After (extracted to shared module):

# validators/request.py
def validate_request_body(body, required_fields):
    if not body:
        raise HTTPError(400, "Request body required")
    for field in required_fields:
        if field not in body:
            raise HTTPError(400, f"Missing field: {field}")

# Each route file now imports:
from validators.request import validate_request_body

Priority: High -- 3 exact duplicates, Rule of Three applies.

Red Flags -- STOP and Simplify

Same logic in 3+ places
Function > 40 lines
Nesting > 3 levels
Abstract class with one concrete implementation
Wrapper that just delegates
Config for a value used in one place
Try/except that re-raises the same exception
Type check for a statically typed parameter
Null check after a function that can't return null
Commented-out code blocks

Common Rationalizations

Excuse	Reality
"We might need it later"	YAGNI. Add it when you need it.
"It's more extensible"	Extensibility without use cases is waste.
"The abstraction makes it cleaner"	One caller = inline is cleaner.
"Deleting code feels risky"	Git remembers. Dead code is maintenance cost.
"It's just a few extra lines"	Lines compound. 10 files x 5 extra lines = 50 lines of noise.
"The AI generated it, it must be right"	AI optimizes for completeness, not simplicity.
"Refactoring might break things"	Tests exist. If they don't, add them first.

Integration

Referenced by:

shipyard:simplifier -- Uses this skill as the analysis framework for cross-task simplification
shipyard:reviewer -- Code quality review (Stage 2) checks for complexity

Pairs with:

shipyard:shipyard-tdd -- Tests make simplification safe
shipyard:shipyard-verification -- Simplification claims need evidence

code-simplification