| name | simplify |
| description | Use when asked to simplify code, clean up tech debt, improve readability, reduce complexity, or make a codebase easier to maintain. |
Goal
Improve the codebase by making it simpler, clearer, more maintainable, and easier to reason about.
The goal is not to make the code look more architected. The goal is to make future changes safer and easier.
Optimize for:
- Less code
- Fewer concepts
- Fewer private/helper functions when they do not improve clarity
- Less duplication
- Clearer names
- More direct control flow
- Smaller public/API surface area
- More obvious behavior
- Better locality of related logic
- Fewer unnecessary abstractions
- Tests that protect behavior
Principles
Prefer deletion over abstraction
Before creating a new abstraction, look for code that can be deleted, inlined, merged, or simplified.
Good cleanup often means removing:
- Dead code
- Unused functions and parameters
- Redundant wrappers
- Trivial private helpers
- Duplicate logic
- Obsolete comments
- Unneeded config
- Defensive code or design that protects no real boundary or failure mode
Do not add abstractions just because two things look similar. Abstract only when the abstraction makes the code easier
to understand and change.
The best cleanup often has a negative diff.
Challenge repeated validation, impossible-state branches, error-hiding fallbacks, and extension points built for
hypothetical needs. Keep a defense only when it protects a reachable failure mode or real boundary, such as untrusted
input, external systems, security, stored data, concurrency, or resource cleanup. Confirm that need from call sites,
types, invariants, tests, or documented behavior.
