Simplify Code

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines; it is code that is easier to read, understand, modify, and debug. Every change should pass this test: would a new team member understand it faster than the original?

When to Use

Use this skill:

• after a feature works and tests pass but the implementation feels heavier than necessary;
• during review when readability or complexity is a concern;
• when logic is deeply nested, functions are long, or names are unclear;
• when refactoring code written under time pressure;
• when consolidating related logic scattered across files;
• after a merge introduced duplication or inconsistency.

Do not use it when code is already clear, when you do not yet understand it, when the simpler version would be measurably slower in a performance-critical path, or when the module is about to be discarded entirely.

Principles

Preserve behavior exactly

Change how the code is expressed, not what it does. Preserve all inputs, outputs, side effects, ordering, errors, timing assumptions, and edge cases. Ask before every change:

• Does every input produce the same output?
• Is error behavior unchanged?
• Are side effects and their ordering preserved?
• Do existing tests pass without modification?

If unsure, do not simplify until the behavior is understood and covered.

Follow project conventions

Read the repository instructions and study neighboring code before editing. Match its conventions for imports, module systems, declarations, naming, errors, and type annotations. A change that breaks local consistency is churn, not simplification.

Prefer clarity over cleverness

Prefer explicit code when a compact expression requires a mental pause. Replace dense ternary chains with guard clauses, named functions, or lookup data. Replace inline reductions with named intermediate values when they make the transformation easier to inspect.

Maintain balance

Avoid over-simplification:

• do not inline a helper that gives an important concept a name;
• do not combine unrelated logic;
• do not remove abstractions that provide extensibility or testability;
• do not optimize for line count.

Scope to what changed

Default to simplifying recently modified code. Do not perform drive-by refactors outside the current task unless the user explicitly broadens the scope.

Process

1. Understand before touching

Apply Chesterton's Fence: understand why a piece of code exists before removing or changing it. Answer:

• What is its responsibility?
• Who calls it and what does it call?
• What are the edge cases and error paths?
• Which tests define the behavior?
• Was it written for performance, a platform constraint, compatibility, or a historical reason?
• What does git blame reveal about its original context?

If these questions cannot be answered, read more context first.

2. Identify concrete opportunities

Look for signals such as:

• three or more levels of nesting: use guard clauses or focused helpers;
• functions longer than roughly 50 lines: split responsibilities;
• nested ternaries: use conditionals, switch, or lookup objects;
• boolean flag parameters such as doThing(true, false, true): use options or separate functions;
• repeated conditions: extract a named predicate;
• generic or abbreviated names such as data, temp, usr, or cfg: rename to describe their meaning;
• misleading names, especially a function named get that mutates state;
• comments that only restate what the code does: remove them;
• comments that explain why a non-obvious decision exists: keep them;
• duplicated logic of several lines: extract a shared function;
• unreachable branches, unused variables, or commented-out blocks: remove after confirming they are dead;
• wrappers that add no value: call the underlying function directly;
• factories or strategies with only one meaningful implementation: use the direct approach;
• redundant type assertions: remove them when inference already proves the type.

3. Apply changes incrementally

Make one simplification at a time. Run tests after each meaningful change. Keep refactoring separate from feature and bug-fix changes.

For each simplification:

1. Make the change.
2. Run the relevant test suite.
3. If it passes, continue or create a save-point commit.
4. If it fails, revert that simplification and reconsider.

Do not batch several untested simplifications. If something breaks, the cause should be identifiable. If a refactor would touch more than 500 lines, use codemods, AST transforms, or another repeatable automation instead of editing manually at that scale.

4. Verify the result

Compare before and after:

• Is the new code genuinely easier to understand?
• Does it follow project conventions?
• Is the diff clean and reviewable?
• Would a teammate approve it as a net improvement?

If the simplified version is harder to understand or review, revert it. Not every simplification attempt succeeds.

Common Rationalizations

Red Flags

Stop and reconsider when:

• tests must be modified only to make the simplification pass;
• the simplified code is longer or harder to follow;
• names are being changed to match personal preference rather than project convention;
• error handling is removed because it looks cleaner;
• the code is not fully understood;
• many simplifications are batched into one hard-to-review change;
• unrelated code is being refactored without authorization.

Verification

After the simplification pass, confirm:

• existing tests pass without modification;
• the build succeeds without new warnings;
• the linter and formatter pass;
• each change is incremental and reviewable;
• the diff has no unrelated changes;
• project conventions are followed;
• no error handling was removed or weakened;
• no unused imports or unreachable branches remain;
• a teammate or review agent would approve the result as a net improvement.

This Skill is adapted from Addy Osmani's code-simplification Skill and renamed to avoid colliding with the architecture-focused find-simplifications Skill.