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
- States Are Business Concepts: "ProcessingPayment" not "step3".
- Transitions Are Events: Every arrow needs a named trigger.
- Guards Prevent Ambiguity: Mutually exclusive and exhaustive.
- Error States Are First-Class: Every state needs an error path.
- Compensating Actions Enable Recovery: For each side effect, define undo.
- Invariants Are Explicit: Violations are bugs, not edge cases.
- Visualization Validates Design: If you cannot draw it, you do not understand it.
Inputs / Outputs
| Input |
Required |
Description |
process_description |
Yes |
Natural language description of the workflow |
domain_context |
No |
Business rules, constraints, existing systems |
| Output |
Type |
Description |
state_machine_spec |
File |
At ~/.local/spellbook/docs/<project>/plans/ |
mermaid_diagram |
Inline |
State diagram for validation |
transition_table |
Inline |
Tabular representation |
State Machine Components
| State Type |
Purpose |
Example |
| Initial |
Entry point (exactly one) |
Draft, New |
| Intermediate |
Processing stages |
UnderReview |
| Terminal |
Happy/failure completion |
Approved, Rejected |
| Error |
Recoverable, can retry |
Failed, Suspended |
Transitions: Source --trigger[guard]/action--> Target
Guards: Must be mutually exclusive when sharing triggers. No implicit else.
Design Process
- State Identification: List status nouns, classify types, name with domain vocabulary
- Transition Mapping: For each state, what events cause exit?
- Guard Design: Ensure mutual exclusivity, explicit exhaustiveness
- Error Handling: Every state needs failure path with retry/escalate/terminate
- 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
- States: Draft (initial), UnderReview (intermediate), Approved/Rejected (terminal), ReviewFailed (error)
- Transitions:
- Draft --submit[valid]--> UnderReview
- UnderReview --approve[hasAuthority]--> Approved
- UnderReview --reject--> Rejected
- UnderReview --error[retryable]--> ReviewFailed
- ReviewFailed --retry[count<3]--> UnderReview
- Validation: All states reachable, no dead ends, guards exclusive
- Output: Mermaid diagram + transition table
Self-Check
If ANY unchecked: revise before completing.
1---2name: designing-workflows3description: Use when designing systems with explicit states, transitions, or multi-step flows. Triggers: "design a workflow", "state machine", "approval flow", "pipeline stages", "what states does X have", "how does X transition", or when implementing-features Phase 2.1 detects workflow patterns.4---5
6# Workflow Design
7
8<ROLE>
9Workflow Architect with formal methods background. Your reputation depends on state machines that are complete (no dead ends), deterministic (unambiguous transitions), and recoverable (graceful error handling). A workflow that hangs or silently fails is a professional failure.
10</ROLE>
11
12## Reasoning Schema
13
14<analysis>Before designing: What are the business states? What events trigger transitions? What invariants? What can fail?</analysis>
15
16<reflection>After designing: Is every state reachable? Can every state exit? Are guards mutually exclusive? Are error states recoverable?</reflection>
17
18## Invariant Principles
19
201. **States Are Business Concepts**: "ProcessingPayment" not "step3".
212. **Transitions Are Events**: Every arrow needs a named trigger.
223. **Guards Prevent Ambiguity**: Mutually exclusive and exhaustive.
234. **Error States Are First-Class**: Every state needs an error path.
245. **Compensating Actions Enable Recovery**: For each side effect, define undo.
256. **Invariants Are Explicit**: Violations are bugs, not edge cases.
267. **Visualization Validates Design**: If you cannot draw it, you do not understand it.
27
28## Inputs / Outputs
29
30| Input | Required | Description |
31|-------|----------|-------------|
32| `process_description` | Yes | Natural language description of the workflow |
33| `domain_context` | No | Business rules, constraints, existing systems |
34
35| Output | Type | Description |
36|--------|------|-------------|
37| `state_machine_spec` | File | At `~/.local/spellbook/docs/<project>/plans/` |
38| `mermaid_diagram` | Inline | State diagram for validation |
39| `transition_table` | Inline | Tabular representation |
40
41---
42
43## State Machine Components
44
45| State Type | Purpose | Example |
46|------------|---------|---------|
47| **Initial** | Entry point (exactly one) | `Draft`, `New` |
48| **Intermediate** | Processing stages | `UnderReview` |
49| **Terminal** | Happy/failure completion | `Approved`, `Rejected` |
50| **Error** | Recoverable, can retry | `Failed`, `Suspended` |
51
52**Transitions:** `Source --trigger[guard]/action--> Target`
53
54**Guards:** Must be mutually exclusive when sharing triggers. No implicit else.
55
56---
57
58## Design Process
59
601. **State Identification**: List status nouns, classify types, name with domain vocabulary
612. **Transition Mapping**: For each state, what events cause exit?
623. **Guard Design**: Ensure mutual exclusivity, explicit exhaustiveness
634. **Error Handling**: Every state needs failure path with retry/escalate/terminate
645. **Validation**: Reachable, no dead ends, deterministic
65
66---
67
68## Visualization
69
70```mermaid
71stateDiagram-v2
72 [*] --> Draft
73 Draft --> UnderReview: submit [isValid]
74 Draft --> Draft: submit [!isValid]
75 UnderReview --> Approved: approve
76 UnderReview --> Rejected: reject
77 Approved --> [*]
78 Rejected --> [*]
79```
80
81---
82
83## Workflow Patterns
84
85**Saga Pattern:** Side effects + compensating actions in reverse order on failure.
86```
87Step 1: reserveInventory() | Compensate: releaseInventory()
88Step 2: chargePayment() | Compensate: refundPayment()
89On failure at N: Execute compensations N-1 through 1
90```
91
92**Token-Based Enforcement:** Tokens validate allowed transitions, prevent stage skipping.
93
94**Checkpoint/Resume:** Load checkpoint, restore state, re-enter at saved stage.
95
96---
97
98## Example
99
100<example>
101Design: Order approval workflow
102
1031. **States**: Draft (initial), UnderReview (intermediate), Approved/Rejected (terminal), ReviewFailed (error)
1042. **Transitions**:
105 - Draft --submit[valid]--> UnderReview
106 - UnderReview --approve[hasAuthority]--> Approved
107 - UnderReview --reject--> Rejected
108 - UnderReview --error[retryable]--> ReviewFailed
109 - ReviewFailed --retry[count<3]--> UnderReview
1103. **Validation**: All states reachable, no dead ends, guards exclusive
1114. **Output**: Mermaid diagram + transition table
112</example>
113
114---
115
116<FORBIDDEN>
117- States named after implementation ("step1")
118- Transitions without named triggers
119- Overlapping guards (ambiguous transitions)
120- Missing error handling (only happy path)
121- Side effects without compensating actions
122- Dead-end states not marked terminal
123- Implicit guards ("else" without condition)
124- Skipping completeness validation
125</FORBIDDEN>
126
127---
128
129## Self-Check
130
131- [ ] States use business domain vocabulary
132- [ ] Every transition has named trigger
133- [ ] Guards mutually exclusive and exhaustive
134- [ ] Every non-terminal state has exit
135- [ ] Error states with retry/escalate paths
136- [ ] Side effects have compensating actions
137- [ ] Mermaid diagram renders correctly
138- [ ] Completeness validated
139
140If ANY unchecked: revise before completing.
141
142---
143
144<FINAL_EMPHASIS>
145Workflows 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.
146</FINAL_EMPHASIS>
majiayu000