State Machine Modeling

Concept of the skill

What it is: State-machine modeling is the discipline of making one lifecycle's legal behavior explicit before implementation — what an entity can be, what can happen to it, which happenings are legal in which state, and what must be true before and after each transition. The whole point is to move the rules for "what can follow what" out of scattered if-blocks and into one inspectable model, so that the set of reachable conditions is a deliberate enumeration rather than the accidental product of every boolean someone added.

Mental model — five primitives:

• States — the mutually exclusive conditions one entity or workflow can occupy.
• Events or commands — what triggers change.
• Transitions — the map from (current state, event) to a next state or a deterministic rejection.
• Guards — pure conditions that must hold before a transition can fire.
• Actions / side effects — work attached to entry, exit, or the transition itself; never the state change.

Analogy: Treat the lifecycle like a railway switchboard — the current track segment and signal determine which next track is legal, while maintenance work and passenger notifications happen after the routing decision is made.

Why it exists: Without an explicit machine, lifecycle rules scatter across booleans, if branches, handlers, jobs, and UI checks. That implicit machine admits impossible combinations, makes retries ambiguous, and leaves future implementers guessing which transitions are legal.

What it is NOT: It is not broad domain discovery, persistence schema design, HTTP resource design, frontend state-location strategy, or post-failure debugging. Those skills compose with this one after the lifecycle model is clear.