Simplify

The goal is the simplest code that correctly solves the actual problem — not the most flexible, most abstract, or most clever. Most complexity is accidental: abstractions built for futures that never arrived, duplication from copy-paste, and indirection that hides intent. Delete it, don't decorate it.

Essential complexity stays — the problem really is hard. Accidental complexity is optional and your job is to remove it without changing behavior.

Pair with [[test-first]] for the safety net, [[incremental-delivery]] for small refactor PRs, [[review-gate]] when the cleanup is ready to merge, [[interface-design]] when simplifying public APIs, [[dependency-hygiene]] when deciding to own code vs import a package, and [[perf-budget]] before "optimizing" structure on hot paths — simpler isn't always faster; measure if latency matters.

When to Use

• Cleaning up after a feature lands or a spike becomes production code
• Code that takes more effort to read than the problem deserves
• A reviewer or you keep getting lost following the flow
• Before extending a messy area — simplify first, then add
• After [[review-gate]] flags unnecessary indirection or duplication
• Choosing between a new dependency and a small amount of owned code ([[dependency-hygiene]])

Skip as the primary skill when:

• The area is under active feature development — finish the behavior, simplify in a follow-up PR
• You don't understand the code yet and have no tests — understand and cover first ([[test-first]])
• The change would alter public contracts without a migration ([[interface-design]], [[migration-path]])

Not a substitute for [[fault-recovery]] — if something is broken, fix the bug first; don't refactor around it blindly.

Process

Work in order. Safety and understanding before deletion.

1. Define scope and the safety net

• Bound the refactor — one module, one flow, one PR. "Simplify the whole app" never finishes.
• Behavior must stay the same unless the task explicitly includes a behavior change — simplification

is not a stealth feature.

• Tests green before you start ([[test-first]]). No tests? Add characterization tests for critical

paths first — even coarse ones beat refactoring blind.

• Small commits — delete dead code in one commit, extract duplication in the next; easy to bisect

if something breaks ([[git-flow]]).

• For public APIs, note callers — simplifying internals is free; changing exports needs care

([[interface-design]]).

Good scope: "Simplify checkout total calculation — one module, tests in checkout.test.ts"
Bad scope:  "Clean up the codebase while I'm here"

2. Understand it fully before changing anything

• Read the code end-to-end — inputs, outputs, side effects, error paths.
• Trace one real scenario through the maze — if you can't, neither can the next reader.
• Identify essential vs accidental complexity:
• Essential — required by the domain (tax rules, auth rules, protocol spec)
• Accidental — wrappers, unused options, duplicate paths, "just in case" layers
• Ask: what is the smallest description of what this does? If the code is 10× longer than that

description, most of the gap is accidental.

Don't simplify what you don't understand — you'll delete load-bearing code.

3. Delete what isn't used (highest ROI, lowest risk)

Start here. Deletion is the purest simplification.

Remove:

• Dead code — unreachable branches, unused functions, orphaned files
• Unused parameters and variables — including "reserved for later" args
• Commented-out blocks — git history remembers; comments rot
• Feature flags and config options nothing sets anymore
• Imports and dependencies pulled in but unused ([[dependency-hygiene]])
• Speculative types/interfaces with no implementations or callers

Run the test suite and linter after each deletion batch. If nothing breaks, it wasn't load-bearing.

Red flag: export function handleLegacyV1() { ... }  // zero callers in repo
Action:   delete (or confirm external consumer first)

4. Remove real duplication — not coincidental similarity

Duplication is two places that change for the same reason. Similar-looking code that evolves independently should stay separate ([[interface-design]] — don't force false coupling).

When duplication is real:

• Rule of Three — first occurrence, second duplicate, third time extract a shared helper.

Premature extraction creates the wrong abstraction.

• Extract the idea, not the lines — name the helper for what it means (computeLineTax), not

doStuffFromCartAndCheckout.

• Prefer one obvious home for shared logic — utils module, domain service, not a new helpers2.

When not to extract:

• Two snippets look alike but have different failure modes or change triggers
• Extraction would require boolean flags (if (forCheckout)) — worse than two clear functions

5. Collapse needless indirection

Every layer must earn its keep — hide a seam, swap implementations, or isolate a trust boundary.

Indirection that's worth keeping:

• Multiple real implementations behind one interface
• Clear module boundary between teams or deploy units
• Test seam (inject dependency) with more than one production path

If removing a layer makes testing harder, keep a thin seam — not a cathedral.

6. Simplify control flow and state

• Replace deep nesting with early returns (guard clauses) — fewer variables in scope at once.
• Collapse boolean explosion — five params × three flags → config object or explicit types/states.
• Replace state machines drawn with flags — isLoading && !isError && hasData → enum/status field

with valid transitions only.

• Fewer mutable variables — prefer deriving values during render/calculation over sync effects

([[react-patterns]]).

• Remove special cases by making the general case handle them — often the data model is wrong

([[data-modeling]]).

Before: if (x) { if (y) { if (!z) { doThing(); } } }
After:  if (!x || !y || z) return; doThing();

7. Replace clever with clear

Clever code is read many times and understood once.

• Prefer obvious constructs over terse tricks — readable loop over chained one-liner.
• Name for intent — retryCount not n, expiredToken not t.
• Replace magic numbers/strings with named constants when meaning isn't obvious.
• Delete comments that restate the code; keep comments that explain why a non-obvious rule exists.
• If you need a comment to explain what a line does, rewrite the line.

Clarity is not "more lines" — often the clear version is shorter.

8. Simplify data and API surfaces

• Fewer parameters — if a function takes 8 args, group related ones or pass a typed object with

a small surface ([[interface-design]]).

• Flatten deep JSON only when callers need it flat — don't map-unmap-map for sport.
• Remove optional fields nobody passes — YAGNI on API shape.
• Prefer plain data over objects with behavior when behavior is one function away.
• Delete unused exports — public surface is a promise; shrink it when callers allow

([[migration-path]] if breaking).

9. Prefer owning small code over heavy dependencies

Before adding or keeping a package for a trivial job ([[dependency-hygiene]]):

Ask: Would ~20 lines of boring code be simpler than this dependency + its upgrade path?

Simplify by removing dependencies when:

• You use one function from a large library
• The dependency pulls transitive weight for a one-liner
• The API is harder to learn than the problem

Keep the dependency when security, correctness, or maintenance cost clearly favors it (crypto, parsing complex formats). Document the choice in [[decision-docs]] if non-obvious.

10. Refactor in small, behavior-preserving steps

The sequence that works:

1. Green tests
2. One simplification (delete, inline, extract, rename)
3. Green tests again
4. Commit
5. Repeat

Never combine behavior change + structural refactor in one commit — reviewers and bisect can't tell what broke. If simplification reveals a bug, fix in a separate commit with a regression test ([[fault-recovery]]).

For large messes, strangler approach ([[incremental-delivery]]): simplify the path you're about to touch; leave unrelated tangles for later scoped PRs.

11. Know when to stop

Stop simplifying when:

• Further change needs a behavior decision — that's product/spec, not cleanup
• You're adding abstraction to make it "more flexible" — YAGNI
• Perf-critical path — measure before restructuring ([[perf-budget]]); clearer code that doubles

allocations on the hot path may need a different trade-off

• The result is smaller but harder to read — wrong extract; revert and try again
• Diminishing returns — two readable functions beat one "elegant" meta-function

Ship the PR when behavior is unchanged, tests green, and a stranger could follow the flow faster.

Common Rationalizations

• "We might need it later." — Add it later when "later" is real; YAGNI beats speculative flexibility.
• "It's clever, leave it." — Clever code is cursed on every read; clear wins.
• "Touching it is risky." — With tests, the bigger risk is leaving the maze for the next hurried edit.
• "It works, don't refactor." — Working but unreadable code is a future bug factory.
• "One more abstraction will make it clean." — Abstractions accumulate; deletion and inlining clean better.
• "I'll simplify while adding the feature." — Mixed PRs are hard to review; separate cleanup when possible.
• "Duplication is DRY violation — extract now." — Wrong abstraction is worse than two clear copies.
• "Removing the dependency is too much work." — Transitive deps are permanent work; weigh honestly.

Red Flags

• Abstractions with exactly one implementation or caller
• Same logic copy-pasted in several places with no extract plan
• Layers that only pass calls through unchanged
• Functions you re-read three times to follow
• Flags and config options nothing sets
• "Flexible" frameworks built for requirements that don't exist
• Refactor PR with no tests and wide diff
• Public API changed without caller updates or migration note
• New helper file created for one 3-line function used once
• utils, helpers, common folders growing without domain meaning
• Simplification that adds more lines than it removes

Verification

• [ ] Scope bounded; behavior unchanged unless explicitly in scope
• [ ] Tests green before and after; characterization tests added if none existed
• [ ] Dead code, unused params, orphaned flags, and unused deps removed
• [ ] Real duplication extracted (Rule of Three); coincidental similarity left alone
• [ ] Single-use indirection inlined; remaining layers earn their keep
• [ ] Control flow and state reduced — early returns, fewer flags, clearer status
• [ ] Clever constructs replaced with clear names and obvious logic
• [ ] Public API surface not accidentally shrunk or expanded without [[interface-design]] / [[migration-path]]
• [ ] Refactor in small commits; no behavior change mixed with structural cleanup
• [ ] Result is smaller or same size, strictly easier to read — not a new abstraction maze