Workflow Design

Reasoning Schema

Before designing: What are the business states? What events trigger transitions? What invariants? What can fail?

After designing: Is every state reachable? Can every state exit? Are guards mutually exclusive? Are error states recoverable?

Invariant Principles

1. States Are Business Concepts: "ProcessingPayment" not "step3".
2. Transitions Are Events: Every arrow needs a named trigger.
3. Guards Prevent Ambiguity: Mutually exclusive and exhaustive.
4. Error States Are First-Class: Every state needs an error path.
5. Compensating Actions Enable Recovery: For each side effect, define undo.
6. Invariants Are Explicit: Violations are bugs, not edge cases.
7. Visualization Validates Design: If you cannot draw it, you do not understand it.

Inputs / Outputs

State Machine Components

Transitions: Source --trigger[guard]/action--> Target

Guards: Must be mutually exclusive when sharing triggers. No implicit else.

Design Process

1. State Identification: List status nouns, classify types, name with domain vocabulary
2. Transition Mapping: For each state, what events cause exit?
3. Guard Design: Ensure mutual exclusivity, explicit exhaustiveness
4. Error Handling: Every state needs failure path with retry/escalate/terminate
5. Validation: Reachable, no dead ends, deterministic

Visualization

stateDiagram-v2
    [*] --> Draft
    Draft --> UnderReview: submit [isValid]
    Draft --> Draft: submit [!isValid]
    UnderReview --> Approved: approve
    UnderReview --> Rejected: reject
    Approved --> [*]
    Rejected --> [*]

Workflow Patterns

Saga Pattern: Side effects + compensating actions in reverse order on failure.

Step 1: reserveInventory() | Compensate: releaseInventory()
Step 2: chargePayment()    | Compensate: refundPayment()
On failure at N: Execute compensations N-1 through 1

Token-Based Enforcement: Tokens validate allowed transitions, prevent stage skipping.

Checkpoint/Resume: Load checkpoint, restore state, re-enter at saved stage.

Example

1. States: Draft (initial), UnderReview (intermediate), Approved/Rejected (terminal), ReviewFailed (error)
2. Transitions:
   • Draft --submit[valid]--> UnderReview
   • UnderReview --approve[hasAuthority]--> Approved
   • UnderReview --reject--> Rejected
   • UnderReview --error[retryable]--> ReviewFailed
   • ReviewFailed --retry[count<3]--> UnderReview
3. Validation: All states reachable, no dead ends, guards exclusive
4. Output: Mermaid diagram + transition table

Self-Check

• States use business domain vocabulary
• Every transition has named trigger
• Guards mutually exclusive and exhaustive
• Every non-terminal state has exit
• Error states with retry/escalate paths
• Side effects have compensating actions
• Mermaid diagram renders correctly
• Completeness validated

If ANY unchecked: revise before completing.

<FINAL_EMPHASIS> Workflows are contracts. Every state is a promise. Every transition is a fulfillment. Every guard is a condition. A well-designed workflow proves your system cannot get stuck, lose work, or silently fail. The mermaid diagram IS the design. </FINAL_EMPHASIS>