Workflow Audit Skill
<workflow-audit>Quick Ref: 5-layer UI workflow audit: discover entry points → trace flows → detect issues → evaluate UX → verify data wiring. Output:
.workflow-audit/in project root.
You are performing a systematic workflow audit on this SwiftUI application.
Required output: Every finding MUST include Urgency, Risk, ROI, and Blast Radius ratings using the Issue Rating Table format. Do not omit these ratings.
Quick Commands
| Command | Description |
|---|---|
/workflow-audit | Full 5-layer audit |
/workflow-audit layer1 | Discovery only — find all entry points |
/workflow-audit layer2 | Trace — trace critical paths |
/workflow-audit layer3 | Issues — detect problems across codebase |
/workflow-audit layer4 | Evaluate — assess user impact |
/workflow-audit layer5 | Data wiring — verify real data usage |
/workflow-audit trace "A → B → C" | Trace a specific user flow path |
/workflow-audit diff | Compare current findings against previous audit |
/workflow-audit fix | Generate fixes for found issues |
/workflow-audit status | Show audit progress and remaining issues |
Overview
The Workflow Audit uses a 5-layer approach:
| Layer | Purpose | Output |
|---|---|---|
| Layer 1 | Pattern Discovery - Find all UI entry points | Entry point inventory |
| Layer 2 | Flow Tracing - Trace critical paths in depth | Detailed flow traces |
| Layer 3 | Issue Detection - Categorize issues across codebase | Issue catalog |
| Layer 4 | Semantic Evaluation - Evaluate from user perspective | UX impact analysis |
| Layer 5 | Data Wiring - Verify features use real data | Data integrity report |
Reference Documentation
Read these files for methodology and patterns (paths relative to this skill's directory):
agents/README.md- Overview and quick startagents/layer1-patterns.md- Discovery regex patternsagents/layer2-methodology.md- Flow tracing processagents/layer3-issue-detection.md- Issue categoriesagents/layer4-semantic-evaluation.md- User impact analysisagents/layer5-data-wiring.md- Data integrity methodology
For templates and examples:
agents-skill/templates/- YAML templates for each layeragents-skill/examples/- Good and bad patterns
Note: These paths are relative to the skill directory (
~/.claude/skills/workflow-audit/). When reading these files, resolve from the skill's installed location, not the current working directory.
Issue Categories
| Category | Severity | Description |
|---|---|---|
| Dead End | 🔴 CRITICAL | Entry point leads nowhere |
| Wrong Destination | 🔴 CRITICAL | Entry point leads to wrong place |
| Mock Data | 🔴 CRITICAL | Shows fabricated data when real data exists |
| Destructive Without Confirm | 🔴 CRITICAL | Delete/clear with no confirmation dialog |
| Silent State Reset | 🔴 CRITICAL | In-progress work lost on navigate away |
| Incomplete Navigation | 🟡 HIGH | Must scroll/search after landing |
| Missing Auto-Activation | 🟡 HIGH | Expected mode/state not set |
| Unwired Data | 🟡 HIGH | Model data exists but feature ignores it |
| Platform Parity Gap | 🟡 HIGH | Works on one platform, broken on another |
| Promise-Scope Mismatch | 🟡 HIGH | Specific CTA opens generic destination |
| Buried Primary Action | 🟡 HIGH | Primary button hidden below scroll fold |
| Dismiss Trap | 🟡 HIGH | Only Cancel/back visible, no forward path |
| Context Dropping | 🟡 HIGH | Item context lost between platforms/notifs |
| Notification Nav Fragility | 🟡 HIGH | Untyped dict used for navigation context |
| Sheet Presentation Asymm | 🟡 HIGH | Different sheet mechanisms per platform |
| Empty State Missing | 🟡 HIGH | Blank screen when list empty |
| Error Recovery Missing | 🟡 HIGH | Error shown but no retry or recovery path |
| Keyboard Obscures Input | 🟡 HIGH | TextField covered by keyboard, no scroll |
| Permission Denied Dead End | 🟡 HIGH | Denied with no path to Settings |
| Modal Stacking | 🟡 HIGH | Multiple sheets/alerts stacked |
| Nav Container Mismatch | 🟡 HIGH | Selection tag invalid for current container |
| Two-Step Flow | 🟢 MEDIUM | Intermediate selection required |
| Missing Feedback | 🟢 MEDIUM | No confirmation of success |
| Gesture-Only Action | 🟢 MEDIUM | Only accessible via swipe/long-press |
| Loading State Trap | 🟢 MEDIUM | Spinner with no cancel/timeout/escape |
| Stale Navigation Context | 🟢 MEDIUM | Cached context never cleared/validated |
| Phantom Touch Target | 🟢 MEDIUM | Looks tappable but has no action |
| Race Condition UX | 🟢 MEDIUM | Conflicting ops triggered simultaneously |
| Invisible Selection | 🟢 MEDIUM | Selected/active but no visual indicator |
| Inconsistent Pattern | ⚪ LOW | Same feature accessed differently |
| Orphaned Code | ⚪ LOW | Feature exists but no entry point |
| Double-Nested Navigation | ⚪ LOW | NavigationStack inside NavigationStack |
Design Principles
1. Honor the Promise
When a button/card says "Do X", tapping it should DO X. Not "go somewhere you might find X."
2. Context-Aware Shortcuts
If user's context implies a specific item, skip pickers.
3. State Preservation
When navigating to a feature, set up the expected state.
4. Consistent Access Patterns
Same feature should be accessed the same way everywhere.
5. Data Integrity
If the app tracks data relevant to a feature, the feature must use it. Never show mock/hardcoded data when real user data exists. Never ignore model relationships that would improve decisions.
6. Primary Action Visibility
The primary action must be visible without scrolling after the user completes the key interaction. Pin Save/Continue/Done buttons outside ScrollView or in toolbar. Never bury them below tall content.
7. Escape Hatch
Every view must have a visible way to go forward OR back. Cancel alone is not enough after user completes a step.
8. Gesture Discoverability
Every action available via gesture (swipe, long-press) should also be accessible via a visible button or menu.
Freshness
Base all findings on current source code only. Do NOT read prior
workflow-audit reports from .workflow-audit/ or .agents/ (they are
stale). DO read companion handoff YAML from sibling skills (radar-suite,
ui-path-radar) — they describe the current codebase from a different
angle, not stale findings. Ignore cached findings from auto-memory or
previous sessions.
Session Setup
Session Setup is defined in radar-suite-core.md (4 questions: experience, table format, fix handling, optional explanation). Use that — do not duplicate it here.
When question 4 ("Explain what this skill does?") is answered "Yes, briefly," substitute these workflow-audit-specific explanations for the generic ones in the inherited core:
- Beginner: "Workflow Audit checks every button, link, and menu item in your app to make sure they work correctly. Think of it like testing every door in a building -- does it open? Does it lead where the sign says? Does anything break along the way? It runs in 5 layers, each going deeper into your app's user experience."
- **Intermedi