states

State coverage

Find the interface people encounter outside the ideal screenshot, whether the input is a spec, a runnable preview, or a live screen. A complete specification is not a prerequisite: inspecting incomplete work is the purpose of this skill.

Work

• Identify actual data dependencies, roles, network calls, writes, and navigation paths.
• Separate initial loading from refresh; never-created data from filtered no-results; missing optional data from failed data; rejected writes from unknown outcomes.
• Inspect reachable permission, session, offline, conflict, partial-success, cancellation, and retry states. Mark irrelevant states rather than generating UI for them.
• For each gap, name the trigger, visible explanation, next action, retained input/data, and the layer responsible.
• Prioritize data loss, blocked primary tasks, misleading success, and access failures before minor polish.
• On live work, reproduce with safe test data. Do not fabricate that a state was observed or exercise consequential production actions just to complete coverage.

Deliver

Report a compact table: scenario → observed/planned behavior → recovery → priority → verification. Include copy when ambiguity causes the failure. If fixes were requested, implement the reachable states and replay them.

## State coverage

Scenario	Observed / planned behavior	Recovery	Priority	Verification
			Must / Should / Later

Critical missing

• [item]

Copy

• [item]

Check that errors stay visible where action is needed, pending work is distinguishable from completion, and input survives safely. Avoid mandatory skeletons, illustrations, toasts, or confirmation dialogs without a task reason. Use `$readiness` when these findings inform a release decision.

## Worked example

```markdown
## State coverage

| Scenario | Observed / planned behavior | Recovery | Priority | Verification |
|---|---|---|---|---|
| Project list first load | Skeleton rows hold layout; no full-screen spinner | None needed | Must | Render with throttled network; confirm no layout shift |
| No projects yet | Empty panel with "Create project" action | Create project | Must | Render with zero fixtures; confirm action routes correctly |
| Refresh fails after data loaded | Keep stale list with "data from [time]" notice plus inline retry | Retry | Must | Fail refresh; confirm stale rows persist and retry clears the error |
| Viewer opens admin settings | Settings hidden; direct URL shows explanation and a back action | Back to dashboard | Must | Request as viewer; confirm no admin mutation fires |
| Create fails on network | Preserve form input; show inline error with retry | Retry | Must | Drop network mid-submit; confirm no duplicate on retry |
| Delete project | Confirm dialog naming the project before the mutation fires | Cancel / Delete | Must | Confirm dialog blocks mutation until confirmed |

### Critical missing
- Team page has no empty state; currently renders blank
- Delete project has no confirmation; mutation fires immediately

### Copy
- Refresh error: "We couldn't refresh your projects. Data from 09:41." Action: "Try again"
- Empty: "No projects yet. Create your first one."

Gotchas

• Never-created empty and filtered no-results need different copy: one explains how to start, the other how to adjust the filter.
• A timeout does not mean the write failed; confirm the result before offering retry unless the contract makes retry safe.
• Replacing loaded data with a spinner on refresh hides what the user was reading; keep stale data with a retry.
• An empty optional field is not an error; show errors only for failed requests, and say what failed.
• Clearing a form to display an error is the most common way state handling loses data.
• A state you did not render is a guess; mark it planned, not observed.

Boundaries

• Do not use to design a component's API, variants, or keyboard contract; use $component instead.
• Do not use to map the step-by-step path of a task; use $flow instead. An unmapped flow is not a blocker: trace the path from the running screen.
• Do not use to judge whether a build supports demo, pilot, or production use; use $readiness instead.