| name | failure-path-audit |
| description | Audit all failure paths, edge cases, and non-happy-path states -- empty states, validation errors, permission failures, loading, undo, and recovery. |
| disable-model-invocation | true |
Audit failure paths and edge cases for this scope:
$ARGUMENTS
Use ultrathink. Happy paths make prototypes look coherent. Failure paths reveal whether they actually are. Review the actual codebase, components, error handling, and UI states.
Output
Write docs/hci/failure-path-audit.md unless the user asked for another path.
Create the directory if it does not exist.
Required categories
1) Empty states
For every screen or list that can be empty:
| Screen/component | What is empty | Current empty state treatment | Has illustration/guidance? | Has call to action? | Rating |
Rating: OK = empty state is handled well; PARTIAL = present but incomplete; MISSING = no empty state handling.
Check:
- Does the empty state explain why it is empty?
- Does it tell the user what to do next?
- Does it look intentional or broken?
2) Loading states
For every async operation:
| Operation | Current loading indicator | Location | Blocks interaction? | Has timeout handling? |
Check:
- Is there a loading indicator at all?
- Does it appear immediately or after a delay?
- Can the user still interact with other parts of the page?
- What happens if loading takes more than 5 seconds? 30 seconds?
- Is there a way to cancel?
3) Validation errors
For every form or input:
| Form/input | Validation rules | When validation runs | Error message | Error placement | Recovery path |
Check:
- Are errors shown inline or as a summary?
- Do errors appear on submit or on blur?
- Are error messages specific ("Email must include @") or vague ("Invalid input")?
- Does the form preserve entered data on error?
- Are required fields marked before the user submits?
4) Permission and authorization failures
For every protected action or screen:
| Action/screen | Required permission | What happens without permission | User feedback |
Check:
- Are unauthorized actions hidden, disabled, or shown with an error?
- Does the error explain what permission is needed?
- Does it explain how to get that permission?
- Can users accidentally navigate to pages they cannot use?
5) Network and connectivity failures
| Operation | Behavior on network failure | Retry available? | Data preserved? | Offline fallback? |
Check:
- What happens if the API returns 500?
- What happens if the request times out?
- Is there a global error boundary or does each component handle its own?
- Are partial saves possible?
6) Partial completion
| Flow | Can be partially completed? | What happens if abandoned? | Can be resumed? | Is progress saved? |
Check:
- Multi-step forms: what happens if the user closes mid-flow?
- Drafts: are they auto-saved?
- Bulk operations: what happens if some items succeed and some fail?
7) Undo, cancel, and recovery
| Action | Reversible? | Undo mechanism | Confirmation required? | Time limit on undo? |
Check:
- Destructive actions: is there a confirmation dialog?
- Delete: is it soft delete or permanent?
- Cancel during a flow: does it save progress or discard everything?
- Back button: does it work as expected at every step?
8) Concurrent and conflict states
| Scenario | Current handling | User feedback |
Check:
- What happens if two users edit the same thing?
- What happens if the data changes while the user is viewing it?
- Are there stale state problems?
Summary table
| Category | Items audited | Handled well | Partially handled | Not handled | Critical gaps |
|---|
Synthesis
End with:
- top 5 most likely failure scenarios users will encounter
- top 5 missing or broken failure states
- patterns: which failure category is systematically ignored?
- quickest wins: failure states that are easy to fix
- structural issues: failure handling that requires architectural changes
Quality bar
- Reference actual components, error boundaries, API error handling, and UI states.
- Every happy path implies at least 3-5 failure paths. If you find fewer, look harder.
- A good failure path audit should make the developer uncomfortable. That is the point.
Deliverable style
- Clear headings
- Markdown tables
- Mermaid diagrams where useful
- Direct language
- No filler
