simplify

Simplify

Use this skill to make code smaller, clearer, and easier to reason about. The default posture is deletion, but the goal is not the fewest lines at any cost. The goal is the simplest behavior-preserving shape that a future maintainer can trust.

Use And Near Misses

Use this when:

• refining code you just wrote;
• reviewing a PR or branch for avoidable complexity;
• doing a cleanup pass;
• a value changes names across layers;
• helper functions, wrapper types, or translation objects do not earn their existence;
• one concept has multiple code paths.

Do not use this as the controlling skill when:

• the main task is a correctness, security, or data-loss fix;
• adding tests or safety checks increases lines but reduces risk;
• a public API needs a small adapter for compatibility;
• a domain concept is complex because the domain is complex;
• readability would get worse just to make git diff --stat smaller.

Line count is a signal, not a verdict. If simplification adds lines, explain why the resulting code is still simpler.

Core Questions

Ask these before proposing or accepting a shape:

• Can't we just use the existing value, function, or type?
• How many names does this concept have between source and use?
• Does this layer own a real decision, or is it just passing data through?
• Is this state derived from existing data?
• Is this abstraction used enough to earn a name?
• Would deleting this make the code harder to misuse?

Simplification Moves

Prefer The Direct Version

Before adding a service, helper, or abstraction, write the direct version. If the direct version works and stays readable, use it.

// Overbuilt: strategy object for one lookup.
const resolver = new PriceResolver(items);
const price = resolver.resolve(type);

// Direct.
const price = items.find((item) => item.type === type)?.price ?? null;

Inline Single-Use Helpers

Extract when a helper removes real duplication, names a non-obvious domain operation, or isolates a boundary. Inline when it only wraps a one-liner.