State Machine Review

Review the proposed or implemented lifecycle of a specific workflow or entity. Trace both layers where evidence exists. The code layer covers runtime state, persistence, callbacks, and side effects. The business layer covers the rules that determine who can move a case forward, when prerequisites are met, and when the outcome is complete. For a code-only or design-only input, assess the layer you can inspect and identify what would be needed to compare the two.

Reconstruct the workflow

1. Name the workflow, the identity of one instance (such as order ID plus attempt ID), its entry points, and the reviewer’s scope. For a diff, trace unchanged callers, writers, or consumers when they can alter the changed lifecycle. Use approved requirements and established contracts for expected business behavior. Record missing or conflicting product rules as questions and trace what the implementation actually does under each relevant interpretation.
2. Identify the authoritative state and who may change it. Trace writes and decision reads through state fields, flag combinations, record presence, timestamps, locks, cache, queues, callbacks, timers, and administrative or recovery paths as relevant. A combination is an implicit state when it determines which action can happen next. Distinguish durable business facts from local execution states and derived views. Record which intermediate mismatches are allowed and what makes those views converge.
3. Trace the important transitions using from → event or actor [guard] → to, with the writer, side effects, and evidence. For cross-layer work, connect each business milestone to the code transition or durable fact that satisfies it. Mark the commit or acknowledgment boundary when failure between state persistence and a side effect changes the outcome. A short trace is enough for a narrow review. Use a table or small diagram when multiple writers or workflows make the path hard to follow.

Review the paths