🔍 Discovery Phase - Before You Prompt

Critical: Never skip the discovery phase. Understanding your project requirements thoroughly will save countless hours of development time and prevent major refactoring later.

📋 Project Brief
🎨 Design System Discovery
🗺️ User Journey Mapping
📊 Technical Discovery

Essential Questions Checklist

Before writing any prompt, answer these fundamental questions:

Platform Type & Audience

Public or Private Platform? • Public: Needs SEO, performance optimization, public APIs • Private/Internal: Focus on security, authentication, role-based accessTarget Audience Demographics • Age range and technical proficiency • Geographic location (affects hosting, compliance) • Expected user volume (affects architecture)Device Usage Patterns • Mobile-first, desktop-first, or equal priority? • Native app requirements or PWA sufficient? • Offline functionality needed?

Localization & Accessibility

Language Requirements • English only or multi-language? • RTL support (Arabic, Hebrew, Persian)? • Date/time/currency formatting needsAccessibility Standards • WCAG 2.1 AA or AAA compliance? • Screen reader optimization priority • Keyboard navigation requirementsRegional Compliance • GDPR (Europe) • CCPA (California) • Other regional data protection laws

Content Management

Content Update Frequency • Static content (rarely changes) • Dynamic content (frequent updates) • Real-time content (live data)Content Editors • Technical team only • Marketing/content team • End users (user-generated content)CMS Requirements • Full CMS (Strapi, Sanity, Contentful) • Headless CMS integration • Simple admin panel • Git-based content management

User Management

Authentication Methods • Email/password • Social logins (Google, Facebook, GitHub) • SSO/SAML for enterprise • Passwordless/Magic links • Two-factor authenticationUser Roles & Permissions • Simple (user/admin) • Complex (multiple roles with granular permissions) • Team/organization structures • Invitation systemsUser Data Management • Profile customization needs • Data export requirements (GDPR) • Account deletion workflows • Data retention policies

Technical Requirements

Performance Targets • Page load time requirements • Lighthouse score targets • Concurrent user expectations • API response time SLAsIntegration Needs • Third-party APIs • Payment processing • Email services • Analytics platforms • CRM systemsSecurity Requirements • Data encryption standards • PCI compliance (for payments) • Healthcare compliance (HIPAA) • Financial compliance (SOC 2)

Gather Brand Assets

Brand Guidelines Checklist

Logo files (SVG, PNG in multiple sizes)
Color palette (primary, secondary, semantic colors)
Typography guidelines (font families, sizes, weights)
Spacing system (8px grid, 4px grid, custom)
Icon style (outlined, filled, custom set)
Imagery style (photography, illustration, abstract)
Motion principles (timing, easing functions)

UI Inspiration Research

Browse these resources to gather UI patterns and inspiration for your project

Component Libraries

21st.dev - Modern component patterns
Aceternity UI - Animated components
Tailwind UI - Professional templates
shadcn/ui - Radix-based components
HeroUI - Data-heavy interfaces

Design Inspiration

Dribbble - Creative designs
Behance - Complete case studies
Awwwards - Award-winning sites
Mobbin - Mobile patterns
Page Flows - User flow examples
UI Garage - Categorized patterns

Create Moodboard

Create a moodboard with:

1. Color Exploration
   - Primary palette options
   - Accent colors
   - Semantic colors (success, warning, error)

2. Typography Samples
   - Header styles
   - Body text options
   - Special use cases

3. Component Examples
   - Buttons and CTAs
   - Cards and containers
   - Forms and inputs
   - Navigation patterns

4. Interaction Patterns
   - Hover states
   - Loading animations
   - Transitions
   - Micro-interactions

Collect 5-10 references for each:

- Homepage layouts
- Dashboard designs
- Form interfaces
- Data tables
- Mobile navigation
- Error states
- Empty states
- Success feedback

Define Design Tokens

// design-tokens.ts
export const tokens = {
  colors: {
    primary: {
      50: '#f0f9ff',
      500: '#3b82f6',
      900: '#1e3a8a'
    },
    semantic: {
      success: '#10b981',
      warning: '#f59e0b',
      error: '#ef4444',
      info: '#3b82f6'
    }
  },
  spacing: {
    xs: '0.5rem',  // 8px
    sm: '1rem',    // 16px
    md: '1.5rem',  // 24px
    lg: '2rem',    // 32px
    xl: '3rem',    // 48px
  },
  typography: {
    fontFamily: {
      sans: ['Inter', 'system-ui'],
      mono: ['Fira Code', 'monospace']
    },
    fontSize: {
      xs: '0.75rem',
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem',
      '2xl': '1.5rem',
      '3xl': '1.875rem',
      '4xl': '2.25rem',
    }
  },
  animation: {
    duration: {
      fast: '150ms',
      normal: '250ms',
      slow: '350ms'
    },
    easing: {
      default: 'cubic-bezier(0.4, 0, 0.2, 1)',
      bounce: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
    }
  }
}

User Flow Documentation

Map out complete user journeys before implementation

Primary User Flows

Onboarding Flow

Core Feature Flow

Document each major feature:

Entry points
Decision points
Success paths
Error handling
Exit points

Admin Workflows

Document admin-specific workflows: • Content management paths • User management flows • Settings and configuration • Analytics and reporting

Edge Cases & Error Flows

Document how the system handles errors and edge cases

Common scenarios to document: • Network failures • Invalid data • Expired sessions • Payment failures • Rate limiting • Maintenance mode

Permission Matrices

Feature	Guest	User	Admin	Super Admin
View Public Content	✅	✅	✅	✅
Edit Own Profile	❌	✅	✅	✅
Manage Users	❌	❌	✅	✅
System Settings	❌	❌	❌	✅

Architecture Planning

Define technical requirements before implementation

Analyze data needs:

1. Data Volume
   - Number of records expected
   - Growth projections
   - Storage requirements

2. Data Relationships
   - One-to-one
   - One-to-many
   - Many-to-many
   - Hierarchical

3. Real-time Requirements
   - Live updates needed?
   - Collaboration features?
   - Notification systems?

4. Search & Filtering
   - Full-text search
   - Faceted search
   - Complex filtering
   - Sorting requirements

Set performance targets:

Metrics:
- First Contentful Paint: < 1.2s
- Time to Interactive: < 3.5s
- Cumulative Layout Shift: < 0.1
- JavaScript Bundle: < 200KB

Optimization Strategy:
- Code splitting
- Lazy loading
- Image optimization
- Caching strategy
- CDN configuration

Plan for growth:

1. User Scale
   - Current: 100 users
   - 6 months: 1,000 users
   - 1 year: 10,000 users

2. Data Scale
   - Current: 1GB
   - 6 months: 10GB
   - 1 year: 100GB

3. Traffic Patterns
   - Peak hours
   - Seasonal variations
   - Geographic distribution

Next Step

With discovery complete, proceed to create your planning documents (claude.md and plan.md) →

AI Workflows

Prompting Guide

Model Training

Discovery Phase

🔍 Discovery Phase - Before You Prompt

Essential Questions Checklist

Brand Guidelines Checklist

Component Libraries

Design Inspiration

User Flow Documentation

Architecture Planning

Next Step

​🔍 Discovery Phase - Before You Prompt

Essential Questions Checklist

Brand Guidelines Checklist

Component Libraries

Design Inspiration

User Flow Documentation

Architecture Planning

Next Step

🔍 Discovery Phase - Before You Prompt