---

name: code-simplification
description: >-
Simplifies code for clarity without changing behavior. Use when refactoring
for readability, when code works but is harder to maintain than it should be,
or when reviewing code that has accumulated unnecessary complexity.
Covers the five principles, simplification process, and language-specific guidance.
license: MIT
compatibility: "Any AI coding agent"
metadata:
author: terminal-skills
version: "1.0.0"
category: development
tags: ["refactoring", "simplification", "code-quality"]

Code Simplification

Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass: "Would a new team member understand this faster than the original?"

Instructions

The Five Principles

1. Preserve Behavior Exactly. Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical.

2. Follow Project Conventions. Simplification means making code more consistent with the codebase, not imposing external preferences. Read CLAUDE.md/project conventions first.

3. Prefer Clarity Over Cleverness.

// UNCLEAR: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}

4. Maintain Balance. Watch for over-simplification: inlining too aggressively, combining unrelated logic, removing abstractions that exist for testability, optimizing for line count.

5. Scope to What Changed. Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code.

The Simplification Process

Step 1: Understand Before Touching (Chesterton's Fence)

Before changing anything, answer:

• What is this code's responsibility?
• What calls it? What does it call?
• What are the edge cases and error paths?
• Are there tests defining expected behavior?
• Why might it have been written this way?

Step 2: Identify Opportunities

Pattern	Simplification
Deep nesting (3+ levels)	Guard clauses or helper functions
Long functions (50+ lines)	Split into focused functions
Nested ternaries	if/else chains or lookup objects
Boolean parameter flags	Options objects or separate functions
Generic names (data, temp)	Descriptive names (userProfile)
Duplicated logic	Shared function
Dead code	Remove after confirming
Over-engineered patterns	Direct simple approach

Step 3: Apply Changes Incrementally

One simplification at a time. Run tests after each change. Submit refactoring separately from features.

FOR EACH SIMPLIFICATION:
1. Make the change
2. Run the test suite
3. If tests pass → commit
4. If tests fail → revert and reconsider

The Rule of 500: If a refactoring touches 500+ lines, use automation (codemods, AST transforms) instead of manual edits.

Step 4: Verify

Compare before and after: Is the simplified version genuinely easier to understand? Is the diff clean? Would a teammate approve?

Examples

TypeScript / JavaScript

// SIMPLIFY: Unnecessary async wrapper
// Before
async function getUser(id: string): Promise<User> {
  return await userService.findById(id);
}
// After
function getUser(id: string): Promise<User> {
  return userService.findById(id);
}

// SIMPLIFY: Redundant boolean return
// Before
function isValid(input: string): boolean {
  if (input.length > 0 && input.length < 100) { return true; }
  return false;
}
// After
function isValid(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

Python

# SIMPLIFY: Nested conditionals with early return
# Before
def process(data):
    if data is not None:
        if data.is_valid():
            if data.has_permission():
                return do_work(data)
            else:
                raise PermissionError("No permission")
        else:
            raise ValueError("Invalid data")
    else:
        raise TypeError("Data is None")

# After
def process(data):
    if data is None:
        raise TypeError("Data is None")
    if not data.is_valid():
        raise ValueError("Invalid data")
    if not data.has_permission():
        raise PermissionError("No permission")
    return do_work(data)

Guidelines

Common Rationalizations

Rationalization	Reality
"It's working, no need to touch it"	Hard-to-read code is hard to fix when it breaks
"Fewer lines is always simpler"	A 1-line nested ternary isn't simpler than 5-line if/else
"I'll refactor while adding this feature"	Separate refactoring from feature work for clean reviews

Red Flags

• Simplification that requires modifying tests (you likely changed behavior)
• "Simplified" code that is longer and harder to follow
• Removing error handling for "cleanliness"
• Simplifying code you don't fully understand
• Batching many simplifications into one large commit

Verification

• All existing tests pass without modification
• Build succeeds with no new warnings
• Each simplification is a reviewable, incremental change
• Simplified code follows project conventions
• No error handling was removed or weakened
• No dead code was left behind