| name | workflow-audit |
| description | Systematic UI workflow auditing for SwiftUI applications. Discovers entry points, traces user flows, detects dead ends and broken promises, evaluates from user perspective. |
| version | 1.0.0 |
| author | Stuffolio Development |
| license | MIT |
| tags | ["swiftui","ios","macos","audit","ux","navigation","workflow"] |
Workflow Audit Skill
Systematically audit UI workflows in SwiftUI applications to find dead ends, broken promises, and UX friction before users encounter them.
When to Use
- Pre-release audit - Before App Store submission
- After adding features - Verify new entry points work correctly
- User feedback - When users report "I can't find X"
- Navigation refactoring - Verify nothing broke
- Design review - Evaluate workflow efficiency
Invocation
/skill workflow-audit
Or for specific phases:
/skill workflow-audit layer1 # Discovery only
/skill workflow-audit layer2 # Flow tracing
/skill workflow-audit layer3 # Issue detection
/skill workflow-audit layer4 # Semantic evaluation
/skill workflow-audit fix # Generate fixes for found issues
What It Does
Layer 1: Pattern Discovery
- Scans for sheet triggers, navigation changes, feature cards
- Catalogs all UI entry points
- Flags suspicious patterns for investigation
Layer 2: Flow Tracing
- Traces critical user journeys step by step
- Maps expected vs actual paths
- Identifies where flows break down
Layer 3: Issue Detection
- Categorizes issues by type and severity
- Checks for orphaned views and dead ends
- Audits pattern consistency
Layer 4: Semantic Evaluation
- Evaluates from user perspective
- Assesses discoverability, efficiency, feedback
- Maps violations to design principles
Issue Severity
| Severity | Description | Action |
|---|
| 🔴 Critical | User cannot complete goal | Fix immediately |
| 🟠 High | Extra steps, confusion | Fix before release |
| 🟡 Medium | Friction but completable | Fix if time |
| 🟢 Low | Minor polish | Backlog |
Issue Categories
- Dead End - Entry point leads nowhere
- Wrong Destination - Entry point leads to wrong place
- Incomplete Navigation - User must scroll/search after landing
- Missing Auto-Activation - Expected mode not set
- Two-Step Flow - Intermediate selection required
- Missing Feedback - No confirmation of success
- Inconsistent Pattern - Same feature accessed differently
- Orphaned Feature - Feature exists but no entry point
Design Principles Enforced
1. Honor the Promise
When UI says "Do X", tapping it should DO X.
Not "go somewhere you might find X."
2. Context-Aware Shortcuts
Skip pickers when only one item is eligible.
3. State Preservation
Set expected state when navigating (e.g., selection mode).
4. Consistent Access
Same feature = same access pattern everywhere.
Output Files
After running the skill:
.agents/workflow-audit/
├── layer1-inventory.yaml # All entry points
├── layer1-summary.md # Discovery findings
├── layer2-traces/
│ └── flow-XXX.yaml # Individual flow traces
├── layer2-summary.md # Flow trace findings
├── layer3-results.yaml # Categorized issues
└── layer4-evaluation.md # User impact analysis
Integration
This skill complements:
/axiom:audit accessibility - Can users with disabilities complete flows?/axiom:audit swiftui-nav - Navigation correctness/axiom:audit swiftui-performance - Are flows responsive?
Requirements
- SwiftUI project with Sources/ directory
- Grep/ripgrep available for pattern matching
- Read access to all Swift files
Adaptation
When using on a new project:
- Identify your patterns - How does your app manage sheets/navigation?
- Adapt pattern-library.md - Update grep patterns for your conventions
- Run Layer 1 - Create your entry point inventory
- Prioritize flows - Pick critical paths to trace
- Document issues - Use the templates
- Fix and verify - Apply design principles
Time Estimates
| Phase | Time |
|---|
| Layer 1: Discovery | 30-60 min |
| Layer 2: Flow Tracing | 30-60 min/flow |
| Layer 3: Issue Detection | 1-2 hours |
| Layer 4: Evaluation | 1-2 hours |
| Full Audit | 4-8 hours |
Changelog
v1.0.0 (Feb 2026)
- Initial release
- 4-layer methodology
- Issue category taxonomy
- Pattern library for SwiftUI
- YAML templates for all layers
- Good/bad pattern examples
