principle-model-the-domain

Identify what the code must never allow and how the data gets read, then pick a structure that encodes exactly that, such as a state machine for lifecycle checks or a lookup table for branching spread across files.

Use a state machine when multiple booleans must stay in sync or when phases and lifecycle checks are scattered through the code. A state machine makes invalid state combinations unrepresentable and deletes the synchronization branches.

Common tells include a new feature growing an existing if/else chain by one branch, a second boolean that must stay in sync with the first, and phase-named modules that repeat the same domain rules across steps.

Avoid forcing an abstraction when the current shape is already clear, local, and unlikely to grow. Be skeptical of any structure that adds indirection without removing branches, duplicated rules, invalid states, or lifecycle risk.

Maps, registries, lookup tables, and discriminated unions replace branching spread across files. Reducers or command/event models replace ad hoc state mutations, and queues, caches, or graphs fit specific data access patterns.