code-simplification

What this skill does

# 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.**

```typescript
// 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

```typescript
// 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

```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