Skip to content

State Machines

Status: 🌱

Motivation

Make workflow behavior explicit so invalid transitions become harder to implement and easier to test.

Starter Points

  • Model the real lifecycle first using production evidence, not idealized process docs.
  • Keep an initial small set of states and events; evolve only with evidence.
  • Define transition contracts: preconditions, postconditions, and explicit domain errors.
  • Encode invariants in tests and runtime checks for critical flows.
  • Add transition-level audit data (from, to, event, actor, timestamp).
  • Use state-machine tests as a regression shield before and during legacy refactors.

Starter Diagram

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted: submit
    Submitted --> InReview: start_review
    InReview --> Approved: approve
    InReview --> Rejected: reject
    Approved --> Expired: expire
    Rejected --> Draft: reopen
    Expired --> Draft: reopen

Practical References