home / skills / wellapp-ai / well / state-machine

state-machine skill

safe

This skill documents UI component state machines, maps transitions, and clarifies current versus expected behavior to improve reliability.

npx playbooks add skill wellapp-ai/well --skill state-machine

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.9 KB

---
name: state-machine
description: Document UI component states (current vs expected) with transitions
---

# State Machine Skill

Document the state machine for UI components, comparing current behavior to expected behavior and mapping all state transitions.

## When to Use

- During Ask mode CONVERGE loop for stateful components
- When refactoring existing components with complex state
- Before implementing new interactive UI components

## Instructions

### Phase 1: Identify States

List all possible states for the component:

| State | Current Behavior | Expected Behavior |
|-------|------------------|-------------------|
| Initial | [What happens now] | [What should happen] |
| Loading | [Current loading UX] | [Expected loading UX] |
| Success | [Current success display] | [Expected success display] |
| Error | [Current error handling] | [Expected error handling] |
| Empty | [Current empty state] | [Expected empty state] |

**Common States to Consider:**

| State Type | Examples |
|------------|----------|
| Data states | Initial, Loading, Success, Error, Empty, Stale |
| Interaction states | Idle, Hover, Focus, Active, Disabled |
| Visibility states | Hidden, Visible, Collapsed, Expanded |
| Selection states | Unselected, Selected, Partially selected |
| Validation states | Valid, Invalid, Pending validation |

### Phase 2: Map Transitions

Define what triggers each state change:

| From | To | Trigger | Side Effects |
|------|----|---------|--------------|
| Initial | Loading | User action / Mount | Start fetch |
| Loading | Success | Data received | Populate UI |
| Loading | Error | Request failed | Show error message |
| Loading | Empty | Empty response | Show empty state |
| Error | Loading | Retry clicked | Restart fetch |
| Success | Loading | Refresh clicked | Refetch data |

### Phase 3: State Diagram

Create a Mermaid state diagram:

```mermaid
stateDiagram-v2
    [*] --> Initial
    Initial --> Loading : fetch
    Loading --> Success : data received
    Loading --> Error : request failed
    Loading --> Empty : no data
    Error --> Loading : retry
    Success --> Loading : refresh
    Empty --> Loading : refresh
    Success --> [*] : unmount
```

### Phase 4: Data Requirements

For each state, define what data is needed:

| State | Required Data | UI Elements |
|-------|---------------|-------------|
| Initial | None | Placeholder or skeleton |
| Loading | None | Spinner, skeleton, progress |
| Success | [List required fields] | Full component |
| Error | Error message, retry action | Error banner, retry button |
| Empty | Empty message, CTA | Empty illustration, CTA button |

### Phase 5: Edge Cases

Identify edge cases and how to handle:

| Edge Case | Current | Expected |
|-----------|---------|----------|
| Network timeout | [Current] | Show timeout message, retry option |
| Partial data | [Current] | Graceful degradation, show available |
| Stale data | [Current] | Show stale indicator, background refresh |
| Concurrent updates | [Current] | Optimistic update, rollback on conflict |
| Auth expired | [Current] | Redirect to login, preserve state |

## Output Format

```markdown
## State Machine: [Component Name]

### State Table

| State | Current | Expected | Data Required |
|-------|---------|----------|---------------|
| Initial | [Behavior] | [Behavior] | [Data] |
| Loading | [Behavior] | [Behavior] | [Data] |
| Success | [Behavior] | [Behavior] | [Data] |
| Error | [Behavior] | [Behavior] | [Data] |
| Empty | [Behavior] | [Behavior] | [Data] |

### Transition Diagram

[Mermaid stateDiagram]

### Edge Cases

| Case | Handling |
|------|----------|
| [Case] | [How to handle] |

### Summary
- States: [N] identified
- Transitions: [N] mapped
- Edge cases: [N] documented
```

## Invocation

Invoke manually with "use state-machine skill" or follow Ask mode CONVERGE loop which references this skill.

## Related Skills

- `qa-planning` - Uses states to define test coverage
- `design-context` - Check existing component states in Storybook

Overview

This skill documents UI component state machines by comparing current behavior to expected behavior and mapping all state transitions. It provides a clear checklist and diagram template to capture states, triggers, side effects, required data, and edge-case handling. Use it to align engineering and design on predictable, testable component behavior.

How this skill works

The skill guides you through five phases: identify all relevant states, map transitions with triggers and side effects, produce a state diagram (Mermaid-ready), list data requirements per state, and document edge cases with handling strategies. It outputs a compact state table, a transition diagram, and a short summary so teams can iterate quickly. The result is a single source of truth for component behavior used in development, QA, and design reviews.

When to use it

During Ask mode CONVERGE loop for stateful components
When refactoring components with complex or brittle state
Before implementing new interactive UI components
When writing tests to cover component state transitions
When syncing design and engineering on UX expectations

Best practices

Enumerate both data and interaction states (e.g., Loading, Disabled, Hover) to avoid gaps
Map explicit triggers and side effects for every transition to prevent hidden bugs
Include required data and UI elements per state to guide contract and props design
Create the Mermaid diagram early to visualize flows and surface missing transitions
Document edge cases like timeouts, partial data, and auth expiration with concrete remediation steps

Example use cases

Document a data list component: initial skeleton, loading spinner, empty illustration, success list, error banner
Refactor a multi-step form to cover validation, pending save, optimistic update, and rollback
Define behavior for a file upload widget with progress, success, retry on failure, and cancel states
Align front-end props/contract for a search box that handles idle, typing, results, no-results, and error states
Plan test cases and QA coverage from the state table to ensure transitions are exercised

FAQ

What states should I always include?

At minimum include Initial, Loading, Success, Error, and Empty; add interaction, visibility, selection, and validation states as relevant.

How detailed should the data requirements be?

List the exact fields or props needed to render each state and any fallback behavior for missing or partial data; this helps API contracts and tests.