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.

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

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
my_function() {
  log_info "Entering my_function with args: $*"
  log_debug "Checking if file exists: $1"
  if [ -f "$1" ]; then
    log_info "File found: $1"
    cat "$1"
    log_info "Exiting my_function successfully"
  else
    log_error "File not found: $1"
    return 1
  fi
}

# SIMPLER: Let set -e and meaningful exit codes do the work
my_function() {
  cat "$1"
}

# AI BLOAT: Wrapping simple commands in functions used once
get_current_branch() { git rev-parse --abbrev-ref HEAD; }
get_repo_root() { git rev-parse --show-toplevel; }

# SIMPLER: Inline when used once
branch=$(git rev-parse --abbrev-ref HEAD)

# AI BLOAT: Redundant existence checks
if [ -n "${MY_VAR:-}" ]; then
  if [ "${MY_VAR}" != "" ]; then  # Redundant -- -n already checks this
    process "$MY_VAR"
  fi
fi

# SIMPLER: One check is enough
if [ -n "${MY_VAR:-}" ]; then
  process "$MY_VAR"
fi

Example: Full Simplification Finding

**Context:** Three builder agents each implemented a task touching API endpoints. Each added its own request validation helper.

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