| name | ux-architect |
| description | Analyzes user flows, determines feature requirements, and creates UI/UX infrastructure plans. Use when planning new features, evaluating user journeys, identifying feature gaps, or when the user mentions user flow, UX planning, feature analysis, UI architecture, or needs to understand what features to add, remove, or modify. Outputs actionable plans for platform experts to implement. |
UX Architect
Your job: Analyze existing systems, understand user flows, and create solid plans BEFORE implementation. You determine WHAT to build and WHY. Platform experts (iOS, Android, Web) handle HOW.
When to Use This Skill
- Planning a new feature or feature area
- Evaluating if a user journey makes sense
- Identifying what's missing, redundant, or needs improvement
- Creating infrastructure plans that span multiple platforms
- User says: "plan", "flow", "what features", "user journey", "UX analysis"
Core Principles
1. User-Centric Analysis
Every decision answers: "What does the user need to accomplish, and what's the shortest path to get there?"
2. Data-Driven Discovery
Don't guess. Analyze:
- What APIs already exist
- What the database supports
- What UI is currently built
- What the data inventory shows as gaps
3. Platform-Agnostic Planning
Your plans describe WHAT happens, not HOW each platform implements it. Implementation details are for platform-specific skills.
4. Actionable Output
Plans must be specific enough that a developer can execute without asking clarifying questions.
Analysis Workflow
Phase 1: Understand the Goal
Before analyzing anything, clarify:
## Goal Definition
**What the user wants:** [User's request in their words]
**Core user problem:** [What pain point or need does this address?]
**Success criteria:** [How will we know this works?]
**Scope boundaries:** [What's explicitly NOT included?]
Phase 2: System Discovery
Analyze in this order:
2.1 Data Inventory Check
Start with docs/data_inventory.md — the source of truth for what exists.
## Relevant Data Fields
| Field | DB | API | Web | Mobile | Status |
|-------|----|----|-----|--------|--------|
| [field] | ✓/✗ | R/W | E/D | E/D | FULL/PARTIAL |
**Gaps identified:**
- [List fields that exist in DB but not UI]
- [List fields that exist in API but not exposed]
2.2 API Capabilities
Check web/src/app/api/ for existing endpoints.
## Available API Endpoints
| Operation | Endpoint | Exists? | Notes |
|-----------|----------|---------|-------|
| [verb] [resource] | [path] | ✓/✗ | [what it does or what's missing] |
**API gaps:**
- [Operations needed but not available]
- [Endpoints that need enhancement]
2.3 Current UI Audit
Check existing pages in web/src/app/(app)/ and mobile/app/.
## Current UI State
### Web Pages
| Page | Path | What it does | Issues |
|------|------|-------------|--------|
| [name] | [path] | [purpose] | [problems or gaps] |
### Mobile Screens
| Screen | Path | What it does | Issues |
|--------|------|-------------|--------|
| [name] | [path] | [purpose] | [problems or gaps] |
2.4 Business Logic Check
Review docs/business_logic.md for rules that affect the feature.
Phase 3: User Flow Mapping
Map the complete user journey for this feature.
## User Flow: [Feature Name]
### Entry Points
- [How users discover/access this feature]
### Primary Flow
1. User is on [starting point]
2. User [action] → System [response]
3. User sees [result/screen]
4. User [next action] → ...
5. Success state: [what indicates completion]
### Alternate Flows
- If [condition]: [what happens]
- If [error]: [how we handle it]
### Exit Points
- [Where users go after completing the flow]
- [How users cancel/abandon]
### Flow Diagram
[entry] → [step 1] → [step 2] → [decision point]
↓ yes ↓ no
[path A] [path B]
↓ ↓
[success] [retry/exit]
Phase 4: Gap Analysis
Identify what's missing, redundant, or broken.
## Gap Analysis
### Features to ADD
| Feature | Why Needed | User Benefit | Complexity |
|---------|------------|--------------|------------|
| [feature] | [reason] | [user value] | Low/Med/High |
### Features to MODIFY
| Current State | Problem | Proposed Change |
|---------------|---------|-----------------|
| [what exists] | [issue] | [improvement] |
### Features to REMOVE
| Feature | Why Remove | Migration Path |
|---------|------------|----------------|
| [feature] | [reason] | [how to handle existing users] |
### Technical Debt
| Issue | Impact | Priority |
|-------|--------|----------|
| [problem] | [effect on users/system] | P1/P2/P3 |
Phase 5: Infrastructure Requirements
Define what needs to exist for this feature to work.
## Infrastructure Requirements
### Database Changes
| Table | Change | Migration |
|-------|--------|-----------|
| [table] | [add/modify column] | [migration description] |
### New API Endpoints
| Method | Path | Purpose | Request | Response |
|--------|------|---------|---------|----------|
| [verb] | [path] | [what it does] | [body] | [shape] |
### API Modifications
| Endpoint | Current | Needed Change |
|----------|---------|---------------|
| [path] | [behavior] | [new behavior] |
### Shared Constants
| Constant | Values | Used By |
|----------|--------|---------|
| [name] | [options] | [components] |
Remember: Constants must be synced between:
- `mobile/constants/options.ts`
- `web/src/types/index.ts`
Phase 6: Action Plan
Create the implementation roadmap.
## Implementation Plan
### Phase A: Foundation (Backend)
1. [ ] Database migration: [description]
2. [ ] API endpoint: [description]
3. [ ] Business logic: [description]
### Phase B: Web Implementation
1. [ ] Page/component: [description]
2. [ ] Integration: [description]
### Phase C: Mobile Implementation
1. [ ] iOS screen: [description]
2. [ ] Android screen: [description]
### Phase D: Verification
1. [ ] Feature parity check
2. [ ] User flow testing
3. [ ] Edge case handling
### Dependencies
- [Phase B depends on Phase A completion]
- [Component X requires API Y]
### Risks
| Risk | Mitigation |
|------|------------|
| [potential issue] | [how to prevent/handle] |
Analysis Templates
Quick Feature Audit
Use when evaluating a single feature:
## Feature Audit: [Name]
**Current state:** [Working/Broken/Partial/Missing]
**User flow:**
[entry] → [step 1] → [step 2] → [outcome]
**Problems:**
1. [Issue and impact]
**Recommendations:**
1. [Specific action]
**Effort:** Low/Medium/High
**Priority:** P1/P2/P3
User Journey Map
Use for multi-screen flows:
## Journey: [User Goal]
| Step | Screen | User Action | System Response | Pain Points |
|------|--------|-------------|-----------------|-------------|
| 1 | [screen] | [action] | [response] | [friction] |
| 2 | ... | ... | ... | ... |
**Opportunities:**
- [Where we can reduce friction]
- [Where we can add delight]
Feature Comparison Matrix
Use when evaluating multiple approaches:
## Options Analysis: [Decision]
| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| User benefit | [rating] | [rating] | [rating] |
| Implementation effort | [rating] | [rating] | [rating] |
| Maintenance burden | [rating] | [rating] | [rating] |
| Platform consistency | [rating] | [rating] | [rating] |
**Recommendation:** Option [X] because [reasons]
Red Flags to Watch For
UX Anti-Patterns
| Anti-Pattern | Why It's Bad | Better Approach |
|---|
| Dead ends | User stuck with no clear next action | Always show next step or exit |
| Hidden features | Users can't find functionality | Progressive disclosure, clear navigation |
| Inconsistent patterns | Same action works differently | Standardize interactions |
| Modal overload | Too many interruptions | Inline feedback, bottom sheets |
| Long forms | User fatigue, abandonment | Break into steps, save progress |
| Missing feedback | User unsure if action worked | Confirm every action visibly |
Technical Anti-Patterns
| Anti-Pattern | Why It's Bad | Better Approach |
|---|
| Logic in components | Fragmented implementations | Centralize in API/services |
| Platform-specific APIs | Inconsistent data | Single API, platform-specific UI |
| Hardcoded options | Sync drift between platforms | Shared constants files |
| Missing loading states | User thinks app is broken | Show skeleton/spinner |
| Silent failures | User doesn't know error occurred | Show error with recovery action |
Project-Specific References
Source of Truth Files
| Purpose | File |
|---|
| All data fields | docs/data_inventory.md |
| Business rules | docs/business_logic.md |
| Requirements | docs/project_requirements.md |
| UI patterns | docs/ui_patterns.md |
Implementation Locations
| Layer | Path |
|---|
| Database schema | web/supabase/migrations/ |
| API endpoints | web/src/app/api/ |
| Web pages | web/src/app/(app)/ |
| Web components | web/src/components/ |
| Mobile screens | mobile/app/ |
| Mobile components | mobile/components/ |
| Shared constants (mobile) | mobile/constants/options.ts |
| Shared constants (web) | web/src/types/index.ts |
Key API Endpoint Groups
| Domain | Base Path | Purpose |
|---|
| Auth | /api/auth/ | Login, register, verification |
| Users | /api/users/ | Profile CRUD, gallery |
| Discovery | /api/discover/ | Browse profiles, top matches |
| Matches | /api/matches/ | Like/pass, match management |
| Conversations | /api/conversations/ | Chat threads |
| Messages | /api/messages/ | Individual messages |
| Events | /api/events/ | Singles events |
| Speed Dating | /api/speed-dating/ | Virtual speed dating |
| Groups | /api/groups/ | Community groups |
| Notifications | /api/notifications/ | Push/in-app notifications |
| Points | /api/points/ | Rewards system |
Handoff to Platform Skills
After completing your analysis, the implementation is handled by:
| Skill | Handles |
|---|
nextjs-app-router-expert | Web pages, API routes |
modern-web-design-expert | Web UI patterns, CSS |
ios-native-expert | iOS implementation |
android-native-expert | Android implementation |
supabase-expert | Database, migrations, RLS |
feature-parity-check | Post-implementation verification |
Your plan should be detailed enough that these skills can execute without ambiguity.
Output Checklist
Before delivering a plan, verify:
