volodymyrkoval Design Patterns Advisor
A forcing function for pattern thinking. The goal is not to apply patterns — it's to consciously decide whether one fits. Answer the checklist and self-critique questions before committing to a design.
Step 1 — "Did you consider?" checklist
Work through the relevant groups for the problem at hand. You don't need all groups — skip what clearly doesn't apply. But for every group that might apply, consciously decide, don't silently skip.
Creational
- Are there complex construction sequences, optional parameters, or multi-step object assembly? → Builder
- Does the caller need to create objects without knowing the concrete type? → Factory Method / Abstract Factory
- Are objects expensive to create and mostly identical? → Prototype
- Should exactly one instance coordinate shared state? → Singleton (see self-critique — often wrong)
- Are multiple related families of objects created together? → Abstract Factory
Structural
- Are there cross-cutting concerns (logging, caching, auth, retry) layered onto an existing interface? → Decorator or Proxy
- Do two incompatible interfaces need to work together? → Adapter
- Is there a complex subsystem that callers shouldn't need to understand? → Facade
- Do you have a tree of objects treated uniformly as a whole? → Composite
- Is there a large number of fine-grained objects with shared intrinsic state? → Flyweight
- Do you need to decouple an abstraction from its implementation so both can vary independently? → Bridge
Behavioral
- Does an algorithm or behavior vary by context and might add variants later? → Strategy
- Does an object's behavior depend on its current state and transitions between states? → State
- Do you need to encapsulate a request as an object (undo, queuing, logging operations)? → Command
- Do multiple objects need to react to events from one source, without tight coupling? → Observer / Event Bus
- Is there a fixed algorithm skeleton with steps that vary? → Template Method
- Do you need to traverse a structure without exposing it? → Iterator
- Do you need to add operations to objects without changing their classes? → Visitor
- Do objects need to communicate without knowing about each other? → Mediator
- Do you need to restore an object to a previous state? → Memento
- Do you need lazy evaluation of an expensive computation? → Chain of Responsibility or Lazy Proxy
Data & Persistence
- Do you need to decouple domain logic from data access details? → Repository
- Do multiple repositories need to share a transaction boundary? → Unit of Work
- Do you need expressive, composable query conditions as objects? → Specification
- Is domain data mapping complex and varied? → Data Mapper
Architectural
- Do read and write workloads have different scaling, model, or complexity needs? → CQRS (read references/architectural.md)
- Does a multi-step workflow span services and need rollback / compensation on failure? → Saga (read references/architectural.md)
- Should domain events drive side effects instead of direct calls? → Domain Events / Event-Driven (read references/architectural.md)
- Do you need a full audit trail of state changes? → Event Sourcing (read references/architectural.md)
- Is there a reusable selection / filtering rule that needs to be combined and tested independently? → Specification (read references/architectural.md)
Step 2 — Quick reference table
| Pattern | Use when | Skip when |
|---|---|---|
| Builder | Construction has ≥3 optional parts or a required sequence | A plain constructor or named parameters do the job |
| Factory Method | Caller shouldn't own the concrete type; type may vary by subclass | Type is fixed and caller can just new it |
| Abstract Factory | Multiple related objects must be created as a consistent family | Only one object type is being created |
| Prototype | Cloning is cheaper than fresh construction; templates exist | Objects are cheap or vary little |
| Singleton | Truly one instance coordinates shared, mutable, process-wide state | Two instances would work fine; use DI instead |
| Adapter | Two incompatible interfaces must collaborate | You control both sides — change one instead |
| Decorator | Stack cross-cutting concerns without subclassing | There's only one concern; a subclass or wrapper is clearer |
| Proxy | Control access, add lazy loading, or log before delegation | Direct access works; a function wrapper suffices |
| Facade | Simplify a complex subsystem behind a single entry point | The subsystem is already simple |
| Composite | Trees of objects treated uniformly (files/folders, UI trees) | There's no recursive structure |
| Bridge | Abstraction and implementation must vary independently | Only one dimension varies |
| Flyweight | Thousands of near-identical objects; intrinsic state dominates | Object count is small |
| Strategy | An algorithm varies by context and callers swap it | Only one algorithm exists now and none are planned |
| State | Behavior changes significantly based on discrete state transitions | Logic is simpler as a flag or enum check |
| Command | Encapsulate requests for undo, queuing, or logging | Fire-and-forget calls; no replay/undo needed |
| Observer | Multiple consumers react to events from one producer | One consumer; a direct call is clearer |
| Template Method | A fixed algorithm skeleton has variable steps | Steps vary so much they share no skeleton |
| Iterator | Traverse a collection without exposing its internals | Language provides built-in iteration |
| Visitor | Add operations to a stable object hierarchy without modifying it | The hierarchy changes often (prefer polymorphism) |
| Mediator | Many objects communicate in complex ways; reduce coupling | Two or three objects; direct references are fine |
| Memento | Snapshot and restore state (undo stacks, game saves) | State is cheap to recompute |
| Chain of Responsibility | A request passes through a pipeline of handlers, any of which may handle it | Exactly one handler; routing is fixed |
| Repository | Domain logic must be isolated from persistence mechanics | You're in a CRUD app; Active Record is fine |
| Unit of Work | Multiple repositories share a transaction that must succeed or fail together | Single repository; the ORM handles transactions |
| Specification | Business rules are reusable, combinable, and independently testable | Rules are simple one-off predicates |
| CQRS | Reads and writes diverge in model, scaling, or team ownership | Simple CRUD where one model serves both |
| Saga | Multi-step workflows span services; partial failure needs compensation | The workflow is in one service/transaction |
| Domain Events | Side effects should be decoupled from the action that caused them | Direct method calls communicate intent clearly |
| Event Sourcing | Full audit trail required; temporal queries on state history needed | Current state is all you need |
Step 3 — Self-critique (answer before finalizing)
These questions exist because pattern application is a common source of premature abstraction. A pattern that can't pass this checklist shouldn't be in the plan.
- YAGNI test: Is there actual evidence of the variation or growth that justifies this pattern, or is it a guess? One concrete case does not make a pattern.
- Simpler alternative: Could a well-named function, a plain class, or a direct dependency injection solve this without the pattern's indirection?
- Indirection payoff: What specific, concrete benefit does this pattern's extra layer buy? Name it — "flexibility" alone doesn't count.
- Team legibility: Will the next developer recognize this pattern immediately, or will it read as unnecessary machinery?
- Testability: Does this pattern make the code easier to test, or does it add seams that require more mocking?
- Singleton check: If you're considering Singleton — can a dependency injected instance serve the same purpose? (Almost always yes.)
- Architectural pattern check: If considering CQRS, Saga, or Event Sourcing — is the problem genuinely distributed/multi-service, or would a simpler in-process solution work? These patterns carry significant operational cost.
How planner and lead-dev use this skill
Planner: After drafting component responsibilities, invoke this skill. Run Step 1 for each component. Patterns that pass self-critique become explicit todos. Patterns that fail self-critique get noted as "considered and rejected — reason: X" in Technical Notes.
Lead-dev: Before the first Red phase on a design-heavy todo, invoke this skill to validate the chosen approach. If a better pattern emerges, raise it before writing tests — changing the structural decision mid-cycle is expensive.
Output format: State the pattern, the concrete signal that justified it, and the self-critique answer that cleared it. Example:
Strategy — PaymentProcessor behavior varies by provider (Stripe, PayPal, bank transfer) and new providers are a confirmed roadmap item (Q3). Simpler alternative: a switch statement would work now but breaks OCP on every new provider. Indirection payoff: each provider isolated and independently testable.
For architectural patterns (CQRS, Saga, Event Sourcing, Domain Events, Specification), read references/architectural.md before recommending.