Better Simplicity

Make the solution no more complex than the problem

Reduce the number of concepts a maintainer must understand while preserving real boundaries and intended behavior. Prefer boring, direct code when it expresses the domain accurately.

Own unnecessary complexity

Own complexity that exists without a demonstrated requirement, including unnecessary layers, indirection, generality, configuration, extensibility, and pattern machinery.

Do not own a valid boundary merely because it has multiple files. Ask better-architecture whether the boundary protects dependency direction, better-duplication whether an abstraction represents shared knowledge, and better-maintainability whether local code is hard to follow.

When orchestrated by better-codebase, act last and challenge every proposed change as well as the existing implementation.

Review workflow

1. Establish the real requirements

Identify current implementations, callers, variation points, runtime modes, extension contracts, and documented near-term constraints. Distinguish committed requirements from hypothetical future flexibility.

Do not treat might need, could support, or a generic type parameter as evidence of a requirement.

2. Count concepts and indirection

Trace a representative change or runtime path. Look for:

• interfaces with one implementation and no boundary rationale;
• factories that only call one constructor;
• wrappers that preserve the same API without adding policy or isolation;
• generic frameworks used by one concrete case;
• configuration values that never vary in supported deployments;
• strategy, visitor, builder, mediator, or event machinery without demonstrated variation;
• helper layers that make control flow harder to follow;
• data converted through multiple equivalent representations;
• extension points that make invalid states or combinations possible;
• custom utilities already provided clearly by the language or framework;
• defensive flexibility that has no owner, test, or removal condition.

Complexity can also appear as too many flags, modes, callbacks, lifecycle states, or configuration combinations inside one function. Do not focus only on file count.

3. Find the smallest adequate design

Evaluate simplifications in this order:

1. Delete unused code or configuration.
2. Inline a pass-through abstraction.
3. Replace custom machinery with a clear standard facility.
4. Narrow a generic API to the supported cases.
5. Collapse layers that share the same reason to change.
6. Introduce a small named abstraction only when it removes a real concept burden.

Keep an abstraction when it protects a volatile external service, security or transaction boundary, stable public contract, multiple meaningful implementations, or a tested plugin seam.

4. Challenge every proposal

For each proposed refactor, ask:

• Can the same outcome be achieved by deleting or moving code?
• Does the proposal introduce more concepts than it removes?
• Is the new abstraction named after a real domain concept?
• How many current callers or implementations benefit?
• Which future change is actually committed?
• Can a new maintainer follow the runtime path more directly afterward?
• Is the migration smaller than the maintenance cost being removed?

Reject or shrink proposals that fail this check. Make the rejection visible.

Evidence requirements

Demonstrate unnecessary complexity with exact locations and concrete counts or paths: one implementation, one caller, pass-through methods, unused options, repeated conversions, unreachable variation, or a multi-step trace that provides no policy.

Explain what can be removed and which behavior remains. Do not use line count, file count, pattern names, or personal preference as sufficient evidence.

Implementation rules

When asked to implement:

• add or confirm behavioral protection first;
• remove one layer or variation point at a time;
• prefer deletion over replacement;
• keep public contracts stable or provide an approved migration;
• remove dead tests and configuration only after proving they are unreferenced;
• avoid combining simplification with unrelated renaming or modernization;
• compare the before and after concept count in the result.

Standalone review output

When invoked directly, return:

1. Scope and supported requirements — callers, implementations, modes, and constraints inspected.
2. Findings — exact evidence, unnecessary concepts, smallest simplification, behavior preserved, confidence, and change risk.
3. Proposal challenge — changes considered and how they were reduced or rejected.
4. Considered but rejected — abstractions intentionally retained and why.
5. Verification — checks run and remaining uncertainty.

If no change removes more complexity than it creates, state No actionable simplicity findings.

Guardrails

• Never remove a boundary solely because it has one implementation.
• Never inline code when doing so exposes volatile infrastructure or breaks a public contract.
• Never replace a familiar project convention for marginal brevity.
• Never use YAGNI to dismiss an explicit, near-term requirement.
• Never measure simplicity by fewer files or fewer lines alone.
• Never simplify away error handling, observability, validation, authorization, or transaction semantics.
• Never approve another skill's proposal without performing the challenger pass.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NicolasYusim
• Source: NicolasYusim/better-codebase
• License: MIT

Install and usage instructions live in the source repository linked above.