product-expert-design

What this skill does

# Product Expert Design

Guide for designing agent experts that serve end users through adaptive, personalized experiences.

## Codebase Experts vs Product Experts

| Aspect | Codebase Expert | Product Expert |
| --- | --- | --- |
| **Scope** | One per domain | One per user |
| **Storage** | File system (YAML) | Database (JSONB) |
| **Updates** | After code changes | After user actions |
| **Size** | 300-1000 lines | Typically smaller |
| **Latency** | Not critical | Must be fast |
| **Privacy** | Internal only | User data concerns |

## When to Use

- Building product features that learn from user behavior
- Creating per-user expertise files for personalization
- Implementing AI-driven adaptive UX
- Designing recommendation systems with user mental models
- Evaluating whether product experts are appropriate for your use case
- Building progressive personalization with latency considerations

## Product Expert Architecture

```text
┌─────────────────────────────────────────────────────┐
│ User Action (view, click, purchase, etc.)           │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│ Action Tracker                                      │
│ • Capture action type                               │
│ • Record context (time, device, etc.)               │
│ • Queue for expertise update                        │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│ User Expertise Store (Database)                     │
│ • Per-user JSONB column                             │
│ • Structured preference model                       │
│ • Behavior patterns                                 │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│ UI Generation Agent                                 │
│ • Load user expertise                               │
│ • Generate personalized UI                          │
│ • Adapt recommendations                             │
└─────────────────────────────────────────────────────┘
```

## User Expertise Schema

```json
{
  "user_id": "uuid",
  "created_at": "timestamp",
  "updated_at": "timestamp",

  "preferences": {
    "categories": ["tech", "sports"],
    "price_range": {"min": 50, "max": 500},
    "brands": ["Apple", "Sony"],
    "style": "minimalist"
  },

  "behavior_patterns": {
    "active_hours": [9, 10, 11, 14, 15, 20, 21],
    "device_preference": "mobile",
    "session_length_avg": 420,
    "purchase_frequency": "monthly"
  },

  "interaction_history": {
    "views": [
      {"item_id": "123", "timestamp": "...", "duration": 45}
    ],
    "cart_adds": [
      {"item_id": "456", "timestamp": "..."}
    ],
    "purchases": [
      {"item_id": "789", "timestamp": "...", "amount": 299}
    ]
  },

  "inferred_interests": {
    "high": ["wireless headphones", "smart home"],
    "medium": ["fitness trackers"],
    "low": ["gaming"]
  },

  "recommendations_context": {
    "last_shown": ["item1", "item2"],
    "clicked": ["item1"],
    "dismissed": ["item3"]
  }
}
```

## Act-Learn-Reuse for Products

### ACT: User Takes Action

```typescript
async function trackUserAction(
  userId: string,
  action: UserAction
): Promise<void> {
  // Record the action
  await db.userActions.create({
    userId,
    actionType: action.type,
    context: action.context,
    timestamp: new Date()
  });

  // Queue expertise update
  await expertiseQueue.add({
    userId,
    action,
    priority: getActionPriority(action.type)
  });
}
```

### LEARN: Update User Expertise

```typescript
async function updateUserExpertise(
  userId: string,
  action: UserAction
): Promise<void> {
  // Load current expertise
  const expertise = await loadUserExpertise(userId);

  // Update based on action type
  switch (action.type) {
    case 'view':
      updateViewPatterns(expertise, action);
      break;
    case 'cart_add':
      updatePurchaseIntent(expertise, action);
      break;
    case 'purchase':
      updatePreferences(expertise, action);
      break;
  }

  // Recalculate inferred interests
  expertise.inferred_interests = inferInterests(expertise);

  // Save updated expertise
  await saveUserExpertise(userId, expertise);
}
```

### REUSE: Personalized Experience

```typescript
async function generatePersonalizedUI(
  userId: string
): Promise<UIConfig> {
  // Load user expertise first
  const expertise = await loadUserExpertise(userId);

  // Generate UI based on expertise
  return {
    recommendations: await getRecommendations(expertise),
    layout: selectLayout(expertise.behavior_patterns),
    promotions: filterPromotions(expertise.preferences),
    navigation: prioritizeCategories(expertise.inferred_interests)
  };
}
```

## Latency Considerations

Product experts face latency challenges that codebase experts don't:

### The Problem

```text
User Request → Load Expertise → Generate UI → Response
                    ↓
              Agent thinking time (seconds)
                    ↓
              User waiting... (bad UX)
```

### Solutions

#### 1. Pre-computation

```typescript
// Update expertise async, not on-demand
// Pre-generate UI components during low traffic
```

#### 2. Progressive Loading

```typescript
// Show generic UI immediately
// Load personalized elements async
// Swap in when ready
```

#### 3. Expertise Caching

```typescript
// Cache hot user expertise in Redis
// Invalidate on significant changes only
```

#### 4. Tiered Personalization

```typescript
// Level 1: Instant (cached preferences)
// Level 2: Fast (simple inference)
// Level 3: Deep (full agent, async)
```

## Privacy and Data Handling

### Data Minimization

Only store what you need:

```json
// Good: Store patterns, not raw data
{
  "preferred_price_range": {"min": 100, "max": 300},
  "category_affinity": {"tech": 0.8, "fashion": 0.3}
}

// Bad: Store every view with full context
{
  "views": [/* hundreds of detailed entries */]
}
```

### User Control

Provide transparency and control:

```typescript
interface UserExpertiseControls {
  viewExpertise(): UserExpertise;
  clearExpertise(): void;
  disablePersonalization(): void;
  exportData(): DataExport;
}
```

### Retention Policies

```typescript
// Decay old data
function decayOldInteractions(expertise: UserExpertise): void {
  const cutoff = daysAgo(90);
  expertise.interaction_history =
    expertise.interaction_history.filter(i => i.timestamp > cutoff);
}
```

## When to Use Product Experts

| Use Case | Good Fit? | Notes |
| --- | --- | --- |
| E-commerce recommendations | Yes | High value, clear signals |
| Content personalization | Yes | Engagement improves |
| Search ranking | Yes | User-specific relevance |
| Simple preferences | No | Traditional settings work |
| Compliance-heavy domains | Maybe | Privacy concerns |
| Low-traffic products | No | Not enough data |

## Implementation Checklist

### Database Setup

- [ ] User expertise JSONB column
- [ ] Action tracking table
- [ ] Index on user_id for expertise lookup

### Backend Services

- [ ] Action tracking endpoint
- [ ] Expertise update worker (async)
- [ ] Expertise query API
- [ ] Cache layer (Redis)

### Agent Integration

- [ ] Expertise loading prompt
- [ ] UI generation prompt
- [ ] Recommendation prompt

### Frontend

- [ ] Progressive loading UI
- [ ] Skeleton states while personalizing
- [ ] Fallback to generic experience

### Privacy

- [ ] Data retention policy
- [ ] User control dashboard
- [ ] Export/delete functionality

## Anti-Patterns

| Anti-Pattern | Problem | Solution |
| --- | --- | --- |
| Sync updates | Blocks user | Async queue |
| Unbounded history | DB bloat | Rolling window |
| No fallback | Broken for new users | Default experience |
| Over-personalization | Filter bubble | I