---
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