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:

markdown
1## Goal Definition
2
3**What the user wants:** [User's request in their words]
4**Core user problem:** [What pain point or need does this address?]
5**Success criteria:** [How will we know this works?]
6**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.

markdown
1## Relevant Data Fields
2
3| Field | DB | API | Web | Mobile | Status |
4|-------|----|----|-----|--------|--------|
5| [field] | ✓/✗ | R/W | E/D | E/D | FULL/PARTIAL |
6
7**Gaps identified:**
8- [List fields that exist in DB but not UI]
9- [List fields that exist in API but not exposed]

2.2 API Capabilities

Check web/src/app/api/ for existing endpoints.

markdown
1## Available API Endpoints
2
3| Operation | Endpoint | Exists? | Notes |
4|-----------|----------|---------|-------|
5| [verb] [resource] | [path] | ✓/✗ | [what it does or what's missing] |
6
7**API gaps:**
8- [Operations needed but not available]
9- [Endpoints that need enhancement]

2.3 Current UI Audit

Check existing pages in web/src/app/(app)/ and mobile/app/.

markdown
1## Current UI State
2
3### Web Pages
4| Page | Path | What it does | Issues |
5|------|------|-------------|--------|
6| [name] | [path] | [purpose] | [problems or gaps] |
7
8### Mobile Screens
9| Screen | Path | What it does | Issues |
10|--------|------|-------------|--------|
11| [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.

markdown
1## User Flow: [Feature Name]
2
3### Entry Points
4- [How users discover/access this feature]
5
6### Primary Flow
71. User is on [starting point]
82. User [action] → System [response]
93. User sees [result/screen]
104. User [next action] → ...
115. Success state: [what indicates completion]
12
13### Alternate Flows
14- If [condition]: [what happens]
15- If [error]: [how we handle it]
16
17### Exit Points
18- [Where users go after completing the flow]
19- [How users cancel/abandon]
20
21### Flow Diagram
22[entry] → [step 1] → [step 2] → [decision point]
23                                  ↓ yes        ↓ no
24                              [path A]     [path B]
25                                  ↓            ↓
26                              [success]    [retry/exit]

Phase 4: Gap Analysis

Identify what's missing, redundant, or broken.

markdown
1## Gap Analysis
2
3### Features to ADD
4| Feature | Why Needed | User Benefit | Complexity |
5|---------|------------|--------------|------------|
6| [feature] | [reason] | [user value] | Low/Med/High |
7
8### Features to MODIFY
9| Current State | Problem | Proposed Change |
10|---------------|---------|-----------------|
11| [what exists] | [issue] | [improvement] |
12
13### Features to REMOVE
14| Feature | Why Remove | Migration Path |
15|---------|------------|----------------|
16| [feature] | [reason] | [how to handle existing users] |
17
18### Technical Debt
19| Issue | Impact | Priority |
20|-------|--------|----------|
21| [problem] | [effect on users/system] | P1/P2/P3 |

Phase 5: Infrastructure Requirements

Define what needs to exist for this feature to work.

markdown
1## Infrastructure Requirements
2
3### Database Changes
4| Table | Change | Migration |
5|-------|--------|-----------|
6| [table] | [add/modify column] | [migration description] |
7
8### New API Endpoints
9| Method | Path | Purpose | Request | Response |
10|--------|------|---------|---------|----------|
11| [verb] | [path] | [what it does] | [body] | [shape] |
12
13### API Modifications
14| Endpoint | Current | Needed Change |
15|----------|---------|---------------|
16| [path] | [behavior] | [new behavior] |
17
18### Shared Constants
19| Constant | Values | Used By |
20|----------|--------|---------|
21| [name] | [options] | [components] |
22
23Remember: Constants must be synced between:
24- `mobile/constants/options.ts`
25- `web/src/types/index.ts`

Phase 6: Action Plan

Create the implementation roadmap.

markdown
1## Implementation Plan
2
3### Phase A: Foundation (Backend)
41. [ ] Database migration: [description]
52. [ ] API endpoint: [description]
63. [ ] Business logic: [description]
7
8### Phase B: Web Implementation
91. [ ] Page/component: [description]
102. [ ] Integration: [description]
11
12### Phase C: Mobile Implementation
131. [ ] iOS screen: [description]
142. [ ] Android screen: [description]
15
16### Phase D: Verification
171. [ ] Feature parity check
182. [ ] User flow testing
193. [ ] Edge case handling
20
21### Dependencies
22- [Phase B depends on Phase A completion]
23- [Component X requires API Y]
24
25### Risks
26| Risk | Mitigation |
27|------|------------|
28| [potential issue] | [how to prevent/handle] |

Analysis Templates

Quick Feature Audit

Use when evaluating a single feature:

markdown
1## Feature Audit: [Name]
2
3**Current state:** [Working/Broken/Partial/Missing]
4
5**User flow:**
6[entry] → [step 1] → [step 2] → [outcome]
7
8**Problems:**
91. [Issue and impact]
10
11**Recommendations:**
121. [Specific action]
13
14**Effort:** Low/Medium/High
15**Priority:** P1/P2/P3

User Journey Map

Use for multi-screen flows:

markdown
1## Journey: [User Goal]
2
3| Step | Screen | User Action | System Response | Pain Points |
4|------|--------|-------------|-----------------|-------------|
5| 1 | [screen] | [action] | [response] | [friction] |
6| 2 | ... | ... | ... | ... |
7
8**Opportunities:**
9- [Where we can reduce friction]
10- [Where we can add delight]

Feature Comparison Matrix

Use when evaluating multiple approaches:

markdown
1## Options Analysis: [Decision]
2
3| Criteria | Option A | Option B | Option C |
4|----------|----------|----------|----------|
5| User benefit | [rating] | [rating] | [rating] |
6| Implementation effort | [rating] | [rating] | [rating] |
7| Maintenance burden | [rating] | [rating] | [rating] |
8| Platform consistency | [rating] | [rating] | [rating] |
9
10**Recommendation:** Option [X] because [reasons]

Red Flags to Watch For

UX Anti-Patterns

Technical Anti-Patterns

Project-Specific References

Source of Truth Files

Implementation Locations

Key API Endpoint Groups

Handoff to Platform Skills

After completing your analysis, the implementation is handled by:

Your plan should be detailed enough that these skills can execute without ambiguity.

Output Checklist

Before delivering a plan, verify:

• Goal is clearly defined with success criteria
• Data inventory gaps identified
• API capabilities mapped
• Current UI state documented
• User flow mapped with entry/exit points
• Gap analysis complete (add/modify/remove)
• Infrastructure requirements specified
• Implementation phases defined
• Dependencies and risks identified
• Specific enough for developers to execute