---
name: ux-state-machine
description: 'Defines interface states and transitions for UI-heavy work. Use when a UI change adds async behavior, branching flows or recovery paths that are hard to reason about from the happy path.'
metadata:
  model_tier: medium
  cacheable: 'true'
  output_format: markdown
  paqad-meta: skill.meta.yaml
---

## What It Does

Defines the user-visible states, transitions, and triggers for a changed interface so design, implementation, and documentation all operate from the same state model.

## Use This When

When a UI change introduces new async behavior, branching flows, or recovery paths that are hard to reason about from the happy path alone.

## Inputs

- Read the affected screen or component docs and any existing state inventory first.
- Read `references/state-inventory-template.md` before enumerating states.
- Read `runtime/capabilities/coding/checklists/edge-cases-coding.md` to avoid missing loading, stale, and error paths.

## Procedure

1. Walk `assets/canonical-states.txt` (idle, loading, success, empty, error, disabled, stale, permission, retry); include every state the UI actually exposes.
2. For each transition, name the trigger explicitly (user event, async resolve, timeout, permission denied): never imply it.
3. Build the table per `assets/output.template.md` (From / Trigger / To / Notes).
4. Surface any contradictory or undocumented state under `## Gaps`.
5. Validate with `scripts/lint-output.sh`.

## Output Contract

- Return sections named `State Inventory`, `Transitions`, and `Gaps`.
- Each state entry must name the visible UI condition and the user or system trigger.
- If no gaps remain, write `Gaps: none`.

## Escalate / Stop Conditions

- Ask when the request does not define the source of async updates, permissions, or recovery behavior.
- Warn when two states imply conflicting outcomes for the same trigger.
- Do not collapse materially different visible states into one generic label.

## Resources

- `references/state-inventory-template.md`
- `scripts/lint-output.sh`
- `assets/output.template.md`
- `assets/canonical-states.txt`
- `runtime/capabilities/coding/checklists/edge-cases-coding.md`
- `agents/openai.yaml`