mermaid-state-diagram

Use when the user wants a state machine/state transition diagram derived from code or specs, and the output must be Mermaid stateDiagram-v2 plus an extraction summary.

• Code: UI state (useState/useReducer), state managers (Redux/Zustand/Recoil/Jotai), API handlers, jobs, enums + switch, workflow tables.
• Specs: PRDs, tickets, user flows, error handling, conversation logs.
• If scope is unclear, ask for the target feature or flow.

1. Declare scope in one sentence (what the state machine represents).
2. Collect states from enums, reducers, status variables, steps, routing branches.
3. Collect transitions (events), plus guards and actions/side effects.
4. Normalize synonyms, avoid flag explosion, split into main + substate/composite when needed.
5. Build diagram with initial/terminal states when applicable; include error/cancel/retry paths.
6. Validate: no unreachable states, no accidental dead-ends, add [?] to inferred transitions.

1) Mermaid (code block)

```mermaid

stateDiagram-v2

[*] --> Idle

Idle --> Loading: submit

Loading --> Success: api_ok

Loading --> Error: api_err

Error --> Loading: retry

Error --> Idle: cancel

Success --> [*]

```

2) Extraction summary (bullets)

• Scope: ...
• States: ...
• Events: ...
• Guards: ...
• Actions/Side effects: ...
• Assumptions / Unknowns: ... (explain each [?])

• State definition: a mode where behavior/UI is uniquely determined. Avoid raw flag lists.
• Event definition: user actions, API responses, timeouts, retries, disconnects.
• Labels: event / guard (guard optional). Keep state names short, CamelCase.
• Uncertainty: add [?] to inferred transitions and list them under assumptions.

If you need composite states, choice/fork/join, concurrency, direction, or comments, open references/mermaid-stateDiagram.md.

When useful, add:

• Test coverage ideas: cases that traverse each transition at least once.
• Forbidden transitions: transitions that must not happen per spec.