code-simplification

name	code-simplification
description	Reduce code complexity through targeted refactoring. Use when code is difficult to understand, overgrown, or has accumulated technical debt. Simplify without changing behavior.
version	1.0.0
permissions	["fs.read","fs.write","shell.exec"]
triggers	[{"context":"code is too complex"},{"context":"refactoring needed"},{"context":"reducing technical debt"},{"command":"/review"}]
platforms	["claude-code","cursor","gemini-cli","copilot","codex","opencode","windsurf","kiro"]
dependencies	["test-driven-development@^1.0.0"]
author	codehands-core
signed	true
tier	1

Overview

Simplification is removing complexity without losing capability. Simpler code has fewer bugs, is easier to modify, and costs less to maintain. This skill provides systematic approaches to reducing complexity in existing code.

When to Use

• When a file exceeds 300 lines (consider splitting)
• When a function exceeds 30 lines (consider extracting)
• When nesting exceeds 3 levels (consider early returns)
• When you can't understand a function in 30 seconds
• During /review phase
• NOT during initial implementation (get it working first, then simplify)

Process

1. Ensure Tests Exist

Never refactor without tests. If tests don't exist, write them FIRST following codehands:test-driven-development. The tests are your safety net.

2. Identify Complexity

Smell	Signal
Long function	> 30 lines
Deep nesting	> 3 levels of indentation
Long file	> 300 lines
Long parameter list	> 4 parameters
Repeated code	Same logic in 3+ places
God object	One class doing everything
Feature envy	Function uses another module's data more than its own

3. Apply Targeted Refactoring

• Extract function — Pull out a block with a descriptive name
• Early return — Flatten deep nesting with guard clauses
• Introduce parameter object — Bundle related parameters
• Extract module — Split large files by responsibility
• Replace conditional with polymorphism — When switch/if chains grow
• Inline unnecessary abstraction — Remove layers that add complexity without value

4. Verify Behavior Unchanged

After EVERY refactoring step:

npm test  # All tests still pass — behavior unchanged

If tests break, you changed behavior — undo and try again.

Common Rationalizations

Rationalization	Reality
"This code works, don't touch it"	Working complex code is a maintenance bomb. It works today. Tomorrow someone (including you) needs to modify it and introduces a bug because they couldn't understand it.
"Refactoring takes too long"	Targeted refactoring of one function takes 5-10 minutes. The next developer saves 30 minutes understanding it. Net positive.
"I'll refactor the whole module while I'm here"	Scope creep. Refactor only what's in the path of your current task. Broader refactoring is a separate task with its own plan.

Red Flags

• Refactoring without tests
• Changing behavior during refactoring
• Refactoring code unrelated to the current task
• Adding abstraction layers "for future flexibility"

Verification

• Tests exist before refactoring begins
• All tests pass after each refactoring step
• Behavior unchanged (same inputs → same outputs)
• Complexity reduced (measurable: fewer lines, lower nesting, fewer parameters)
• Code is more readable (a new reader could understand it faster)

See Also

• codehands:test-driven-development — Tests that enable safe refactoring
• codehands:source-driven-development — Understand before simplifying
• codehands:code-review-and-quality — Quality standards