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