# Code Simplification

> Remove accidental complexity without changing behavior — apply Chesterton's Fence

- Skill: `vignesh2027/code-simplification` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vignesh2027/code-simplification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vignesh2027/code-simplification/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vignesh2027 (https://skillmd.com/u/vignesh2027)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vignesh2027/code-simplification

---


## Overview

Every line of code is a liability. Complexity that serves no purpose makes systems harder to understand, harder to test, and harder to change. This skill removes accidental complexity while preserving intentional complexity and essential behavior.

## When to Use

- When a PR review reveals unnecessarily complex code
- When a function is hard to test because it does too many things
- When adding a feature to existing code requires understanding too much context
- As part of the `/simplify` workflow

## Process

### Step 1: Understand before you remove (Chesterton's Fence)
Before removing any code that seems unnecessary: understand why it was written. If you don't know why a fence exists, don't remove it. Find out first.

### Step 2: Identify the complexity types
- **Accidental complexity**: complexity from poor implementation choices
- **Essential complexity**: complexity inherent to the problem domain

Only remove accidental complexity. Essential complexity cannot be removed — only managed.

### Step 3: Look for these simplification opportunities

**Dead code**: Code that is never executed. Remove it (git remembers it).

**Premature abstraction**: Abstractions that are more complex than the thing they abstract. Inline them.

**Unnecessary indirection**: Function A calls function B which calls function C and each is 5 lines. Collapse them.

**Redundant comments**: Comments that say what the code already says. Delete them. Keep comments that explain WHY.

**Magic numbers**: Replace `if (retries > 3)` with `if (retries > MAX_RETRIES)`.

**Over-engineered error handling**: 10 levels of nested try/catch for a case that can't happen. Simplify.

**Duplicate logic**: The same logic in 3 places. Extract to one place.

### Step 4: Simplify in small steps
One simplification at a time. Run tests after each step.

### Step 5: Verify behavior is unchanged
The test suite must pass. If there are no tests, write tests for the behavior you're simplifying before you simplify it.

### Step 6: Check: is it simpler for a new reader?
Have someone unfamiliar with this code read it. Is it easier to understand than before?

## Anti-Rationalizations

**"Removing this might break something I don't know about"**
This is Chesterton's Fence. Understand it first. Then remove it.

**"The abstraction makes it more extensible"**
If you are not extending it now, the abstraction is premature. Three identical lines are better than a wrong abstraction.

## Verification Requirements

- [ ] Every removal preceded by understanding why it was written
- [ ] Tests pass after each simplification step
- [ ] No behavior changes (confirmed by tests)
- [ ] A new reader finds it simpler (validation)