State coverage
Find the interface people encounter outside the ideal screenshot. 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
State coverage
| Scenario |
Observed / planned behavior |
Recovery |
Priority |
Verification |
| Project list first load |
Skeleton rows hold layout; no full-screen spinner |
— |
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
- Give never-created empty and filtered no-results different copy and recovery; one explains how to start, the other how to adjust the filter.
- Give rejected writes and unknown outcomes different recovery; retry only when the contract makes it safe.
- Separate initial loading from refresh; keep stale data visible with a retry instead of replacing it with a spinner.
- Distinguish missing optional data from failed data; do not show an error where there is simply nothing.
- Preserve user input across failure and retry; do not clear a form to display an error.
- Reproduce states with safe test data; do not claim a state was observed without rendering it.
Boundaries
- Do not use when the component contract is undefined — use
$component first.
- Do not use when the entry-to-outcome flow is unknown — use
$flow first.
- Do not use to judge whether a build supports demo, pilot, or production use — use
$readiness instead.
- Do use on a runnable preview or live screen, not only on a spec; missing states in production are the point.
1---2name: states3description: Find and resolve missing states in an existing screen, flow, component, or specification. Use when checking loading, empty, error, permission, offline, or mutation recovery before a review or pilot.4---56# State coverage78Find the interface people encounter outside the ideal screenshot. A complete specification is not a prerequisite: inspecting incomplete work is the purpose of this skill.910## Work1112- Identify actual data dependencies, roles, network calls, writes, and navigation paths.13- Separate initial loading from refresh; never-created data from filtered no-results; missing optional data from failed data; rejected writes from unknown outcomes.14- Inspect reachable permission, session, offline, conflict, partial-success, cancellation, and retry states. Mark irrelevant states rather than generating UI for them.15- For each gap, name the trigger, visible explanation, next action, retained input/data, and the layer responsible.16- Prioritize data loss, blocked primary tasks, misleading success, and access failures before minor polish.17- 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.1819## Deliver2021Report 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.2223```markdown24## State coverage2526| Scenario | Observed / planned behavior | Recovery | Priority | Verification |27|---|---|---|---|---|28| | | | Must / Should / Later | |2930### Critical missing31- [item]3233### Copy34- [item]35```3637Check 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.3839## Worked example4041## State coverage4243| Scenario | Observed / planned behavior | Recovery | Priority | Verification |44|---|---|---|---|---|45| Project list first load | Skeleton rows hold layout; no full-screen spinner | — | Must | Render with throttled network; confirm no layout shift |46| No projects yet | Empty panel with "Create project" action | Create project | Must | Render with zero fixtures; confirm action routes correctly |47| 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 |48| 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 |49| Create fails on network | Preserve form input; show inline error with retry | Retry | Must | Drop network mid-submit; confirm no duplicate on retry |50| Delete project | Confirm dialog naming the project before the mutation fires | Cancel / Delete | Must | Confirm dialog blocks mutation until confirmed |5152### Critical missing53- Team page has no empty state; currently renders blank54- Delete project has no confirmation; mutation fires immediately5556### Copy57- Refresh error: "We couldn't refresh your projects. Data from 09:41." — action "Try again"58- Empty: "No projects yet — create your first one."5960## Gotchas6162- Give never-created empty and filtered no-results different copy and recovery; one explains how to start, the other how to adjust the filter.63- Give rejected writes and unknown outcomes different recovery; retry only when the contract makes it safe.64- Separate initial loading from refresh; keep stale data visible with a retry instead of replacing it with a spinner.65- Distinguish missing optional data from failed data; do not show an error where there is simply nothing.66- Preserve user input across failure and retry; do not clear a form to display an error.67- Reproduce states with safe test data; do not claim a state was observed without rendering it.6869## Boundaries7071- Do not use when the component contract is undefined — use `$component` first.72- Do not use when the entry-to-outcome flow is unknown — use `$flow` first.73- Do not use to judge whether a build supports demo, pilot, or production use — use `$readiness` instead.74- Do use on a runnable preview or live screen, not only on a spec; missing states in production are the point.
mattjmdesign