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

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

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