---
name: velcrafting/state-modeling
source: https://app.decimal.ai/s/velcrafting-state-modeling@1/SKILL.md
source_sha256: efd6f2c2c4ad
---

# Skill: frontend/state-modeling

## Purpose
Make non-trivial UI state explicit and testable by defining:
- state shape
- transitions
- derived selectors
- async and error pathways

Use when UI behavior is more than “render props and call an API”.

---

## Inputs
- Target UI flow (screen/component) and its states
- Events/actions that cause transitions
- Any async edges (fetch, debounce, retry, polling)
- Existing state system:
  - local state / reducer
  - context
  - Zustand/Redux/XState/etc (prefer repo profile)
- Repo profile (preferred): `<repo>/REPO_PROFILE.json`

---

## Outputs
- State model implementation aligned with repo patterns:
  - reducer/state machine/store module as appropriate
- Transition definitions (explicit mapping from event → next state)
- Derived selectors/utilities where needed
- Minimal tests if repo uses state unit tests (recommended when non-trivial)

---

## Non-goals
- Changing backend logic or API contracts
- Introducing new state libraries without explicit request
- Large refactors unrelated to the target flow

---

## Workflow
1) Identify the smallest state model that makes behavior explicit.
2) Enumerate states and events:
   - idle, loading, success, error, empty (if data-driven)
   - plus domain-specific UI states (editing, confirming, submitting, etc.)
3) Implement transitions:
   - event-driven (actions)
   - include error and retry transitions
   - include cancellation/reset paths if applicable
4) Keep rendering components dumb:
   - state model owns transitions
   - UI consumes state + dispatches events
5) Validate with repo commands and minimal tests where appropriate.

---

## Checks
- State transitions cover all expected UI paths
- Async flows have deterministic handling (retry/cancel/timeout if relevant)
- No unreachable or dead-end states introduced
- Typecheck passes (if configured)

---

## Failure modes
- Flow is ambiguous → invoke `$ask-questions-if-underspecified` or `meta/intake-interview`.
- State complexity growing uncontrolled → recommend splitting into sub-flow modules.
- Async edge cases missed → recommend `system/state-machine-mapper` for very complex flows.

---

## Telemetry
Log:
- skill: `frontend/state-modeling`
- state_system_used: `useReducer | zustand | redux | xstate | context | other`
- files_touched
- outcome: `success | partial | blocked`