Claude slash command to generate state machine diagrams to give human a system level view to verify correctness. Reveal logic gaps or avoid unexpected state.

CLAUDE-STATE-MACHINE-DIAGRAMS-COMMAND.md

Install

• Create new commands/ folder into your .claude
• Create new file .claude/commands/state-machine.md with the content in state-machine.md file

Usage

/state-machine all backend components

state-machine.md

Generate state machine diagrams. E.g: "all backend components"

Before starting

Ask the user what diagram format they prefer:

• Mermaid markdown (Recommended) — renders on GitHub, VS Code, and most documentation tools
• DOT/Graphviz — generates SVG/PNG with graphviz tools
• ASCII art — plain text diagrams in markdown

Use their choice for all diagrams below.

Instructions

Create state machine diagrams that include input/output schema contracts and dataflow transactions for the specified components.

For each component, produce:

1. Mermaid stateDiagram-v2 showing all states, transitions, and substates
2. Transition table with columns:
   • Transition (from → to)
   • Trigger (what causes it)
   • Input Schema (data required, with types)
   • Side Effects (DB writes, notifications, external calls)
   • Output Schema (data produced, with types)
3. Dataflow diagram (ASCII) showing data transformation through the key path

Process

1. Explore the codebase to find all stateful logic for the target components — look for:
   • useState, useReducer, enums, status fields, _running flags
   • Database columns with status/state values
   • Conditional transitions (if status == X then Y)
   • Error recovery paths and retry logic
2. Identify every state, including intermediate/transient states and error states
3. Map every transition with its trigger, input contract, and output contract
4. Document dataflow showing how data transforms through transitions
5. Write to STATE-MACHINES.md at the repository root (append if file exists, or create new)
6. Ask the user if they want to add a reference to the state machines document in CLAUDE.md. If yes, include an instruction that STATE-MACHINES.md must be updated whenever stateful logic changes (new states, transitions, schema contracts, or dataflow modifications)

Output format

Use this structure per component:

## N. Component Name

Description of what this component does.

```mermaid
stateDiagram-v2
    [*] --> state1 : trigger\n{ input schema summary }
    state1 --> state2 : trigger\naction taken
```

### Transition Table

| Transition     | Trigger     | Input Schema      | Side Effects | Output Schema     |
| -------------- | ----------- | ----------------- | ------------ | ----------------- |
| `[*] → state1` | description | `{ field: type }` | What happens | `{ field: type }` |

### Dataflow

```
Input: { ... }
    │
    ▼
Transform description
    │
    ▼
Output: { ... }
```

Quality checklist

• Every state reachable from [*] has a path to a terminal state or loops
• Every transition has both input and output schemas with concrete types
• Error/failure states are included (not just happy paths)
• Side effects list DB operations, notifications, and external calls
• Dataflow shows actual field names and transformations, not abstract descriptions

Example usage

/state-machines all backend orchestrator workers
/state-machines the React Dashboard and Assets pages
/state-machines subscription billing pipeline
/state-machines all components with database status fields