Engineering simplicity review
Finds unnecessary layers and speculative generalization while preserving essential correctness, security and recovery behavior.
engineering-simplicity-review
See how it helpsWhen is it useful?
Use when a design or change seems harder to maintain than its current requirements justify.
What does it help you do?
- Evaluates lifecycle complexity rather than minimizing line counts.
- Questions pass-through wrappers and frameworks without real consumers.
- Keeps authorization, transactions and error handling as required foundations.
Try asking this
Review this implementation plan and remove unnecessary indirection while retaining tenant checks, failure handling and the actual acceptance criteria. Compare the proposed service chain with an existing module extension. Keep the option that meets the same acceptance checks with fewer ownership and failure boundaries.
Detailed documentation
Read the skill’s original instructions, examples and checks in their authored language.
Show less
Engineering Simplicity Review
Use this skill when reviewing technical designs, implementation plans, or code diffs to ensure accidental complexity is removed before it becomes a permanent maintenance burden.
What Genuine Simplicity Means
- Lifecycle simplicity over line-count golf: A 40-line explicit module with clear types and error handling is simpler than a clever 8-line meta-programmed one-liner or a "quick hack" that requires weekly manual database fixes.
- Deep modules over shallow pass-through layers (Ousterhout): Every new class, interface, wrapper, or microservice must hide significant complexity behind a simpler interface. If an abstraction has the same surface area as the code it wraps, delete the wrapper.
- Non-negotiable foundations are part of simplicity: Authorization checks, tenant isolation, input validation, transactional integrity, and clear error handling are never "over-engineering" — they are required for a working system.
Checklist for Spotting Accidental Complexity
- Premature generalization & single-implementation interfaces:
- Flag
IFooAdapter,AbstractFooFactory, or strategy registries created when only one concrete implementation exists and no second implementation is scheduled in the current scope. - Require at least three concrete call sites or two real domain variants before extracting a shared framework or configurable abstraction; mere syntactic similarity between two functions is not enough.
- Flag
- Pass-through layers & indirection:
- Flag controllers, services, mappers, and DTOs that copy identical fields across 3–4 layers without transforming semantics or enforcing a boundary.
- Unjustified new dependencies or infrastructure:
- Before adding a third-party package, queue, cache cluster, or state-management library, verify whether standard language/runtime APIs or packages already in
package.json/composer.json/pyproject.tomlsolve the problem. - Weigh total cost of ownership: bundle size, security patching, upgrade churn, and operational failure modes.
- Before adding a third-party package, queue, cache cluster, or state-management library, verify whether standard language/runtime APIs or packages already in
- Full rewrites disguised as features:
- Challenge proposals to rewrite a working module from scratch when a targeted, incremental change or strangler step achieves the goal with far lower regression risk.
- Unmeasured performance complexity:
- Reject complex caching layers, custom memory pools, or denormalized sync pipelines unless tied to a measured bottleneck or explicit capacity requirement.
Review Output Contract
Always pair every critique with a runnable, simpler alternative:
Goal: [The concrete requirement or user outcome] Observation: [The specific layer, dependency, or abstraction that exceeds what the goal requires, and the maintenance/failure cost it introduces] Proposal: [The concrete simpler design using existing codebase primitives, plus its known limits] Trade-off: [What we defer and the exact condition that would justify adding the extra layer later]
Included files 1
SKILL.md