Conversation Phases

Mosaic Builder guides conversations through five distinct phases, each designed to progressively build understanding and confidence in the application structure. This phased approach ensures completeness while maintaining clarity.

The Five Phases Overview

graph LR
    A[Discovering<br/>0-25%] --> B[Clarifying<br/>25-50%]
    B --> C[Proposing<br/>50-75%]
    C --> D[Confirming<br/>75-90%]
    D --> E[Building<br/>90-100%]
    
    style A fill:#3B82F6
    style B fill:#EAB308
    style C fill:#A855F7
    style D fill:#22C55E
    style E fill:#EF4444

| Phase | Readiness | Focus | AI Behavior | |-------|-----------|-------|-------------| | 🔵 Discovering | 0-25% | Understanding requirements | Asks broad questions | | 🟡 Clarifying | 25-50% | Filling gaps | Asks specific questions | | 🟣 Proposing | 50-75% | Suggesting structure | Shows understanding | | 🟢 Confirming | 75-90% | Validating model | Seeks confirmation | | 🔴 Building | 90-100% | Ready to generate | Offers code generation |

Phase 1: Discovering (0-25%)

Purpose

Understand the high-level requirements and domain.

Characteristics

• Broad questions about the application purpose

• Entity discovery from initial description

• Domain identification (e-commerce, CRM, blog, etc.)

• Basic relationship detection

Example Conversation

User: "I need a project management tool" AI Response: > I'll help you build a project management tool. Let me understand your needs: > > - What kind of projects will you manage? > - Who are the users (teams, individuals, clients)? > - What are the main features you need? > - Do you need time tracking or budgets?

DSL State

{
  entities: {
    Project: { confidence: 0.7 },
    User: { confidence: 0.6 }
  },
  relationships: {},
  phase: 'discovering',
  readiness: 15,
  confidence: 0.4
}

Transition Triggers

• At least 2-3 core entities identified

• Basic use case understood

• User has provided initial requirements

Phase 2: Clarifying (25-50%)

Purpose

Fill in missing details and resolve ambiguities.

Characteristics

• Specific questions about entities

• Field identification for each entity

• Relationship clarification

• Business rule discovery

Example Conversation

User: "Projects have tasks assigned to team members with deadlines" AI Response: > Good! I'm understanding the structure better: > > - Should tasks have priorities or statuses? > - Can tasks have multiple assignees? > - Do you need subtasks or dependencies? > - Should we track task history? > - What about comments or attachments?

DSL State

{
  entities: {
    Project: { 
      fields: { name, description },
      confidence: 0.85
    },
    Task: {
      fields: { title, deadline },
      confidence: 0.8
    },
    TeamMember: {
      fields: { name, email },
      confidence: 0.75
    }
  },
  relationships: [
    { from: 'Task', to: 'Project', type: 'many-to-one' },
    { from: 'Task', to: 'TeamMember', type: 'many-to-one' }
  ],
  phase: 'clarifying',
  readiness: 40,
  confidence: 0.65
}

Transition Triggers

• Core entities have fields defined

• Main relationships established

• Business context clear

Phase 3: Proposing (50-75%)

Purpose

Present understood structure and suggest enhancements.

Characteristics

• Structure presentation of current understanding

• Feature suggestions based on domain

• Best practice recommendations

• Pattern application from similar apps

Example Conversation

AI Response: > Based on our discussion, here's what I've designed: > > Core Structure: > - Projects with tasks and milestones > - Team members with roles (manager, developer) > - Task assignments with deadlines and priorities > - Comments for collaboration > > Suggested Additions: > - Task dependencies for better planning > - Time tracking for productivity > - Notifications for updates > - Dashboard for overview > > Does this match your vision? What would you change?

DSL State

{
  entities: {
    Project: { 
      fields: { name, description, status, startDate, endDate },
      confidence: 0.9
    },
    Task: {
      fields: { title, description, status, priority, deadline },
      confidence: 0.9
    },
    TeamMember: {
      fields: { name, email, role, avatar },
      confidence: 0.85
    },
    Comment: {
      fields: { content, createdAt },
      confidence: 0.8
    }
  },
  relationships: [...],
  workflows: {
    assignTask: { ... },
    completeTask: { ... }
  },
  phase: 'proposing',
  readiness: 65,
  confidence: 0.8
}

Transition Triggers

• User validates proposed structure

• No major corrections needed

• Additional features discussed

Phase 4: Confirming (75-90%)

Purpose

Finalize details and ensure everything is correct.

Characteristics

• Validation questions for critical features

• Permission clarification

• Technical choices confirmation

• Edge case handling

Example Conversation

AI Response: > Excellent! Let me confirm the final details: > > ✅ Confirmed Structure: > - Complete project management system > - Role-based permissions (Manager, Member) > - Task workflow with statuses > - Real-time notifications > > Final Questions: > - Database preference? (PostgreSQL recommended) > - Need user authentication? (Yes/No) > - Include email notifications? > - Want a mobile-responsive design? > > We're almost ready to generate code!

DSL State

{
  entities: { /* fully defined */ },
  relationships: [ /* complete */ ],
  pages: {
    dashboard: { ... },
    projectList: { ... },
    taskBoard: { ... }
  },
  workflows: { /* defined */ },
  authentication: {
    type: 'email',
    providers: ['google']
  },
  permissions: [
    { role: 'manager', actions: ['*'] },
    { role: 'member', actions: ['read', 'create:task'] }
  ],
  phase: 'confirming',
  readiness: 85,
  confidence: 0.92
}

Transition Triggers

• All entities have required fields

• Relationships are complete

• User confirms structure

• Technical stack chosen

Phase 5: Building (90-100%)

Purpose

Ready for code generation with complete specifications.

Characteristics

• Generation ready state

• Options presentation for code output

• Deployment guidance

• Next steps recommendations

Example Conversation

AI Response: > 🎉 Your application structure is complete! > > Ready to generate: > - ✅ 5 entities with 23 fields > - ✅ 8 relationships defined > - ✅ Authentication configured > - ✅ Role-based permissions > - ✅ 3 main workflows > > Generation Options: > 1. Prisma schema + migrations > 2. Next.js API routes > 3. React components > 4. Full application scaffold > > Click 'Generate Code' to proceed!

DSL State

{
  // Complete DSL with all fields
  phase: 'building',
  readiness: 95,
  confidence: 0.95,
  metadata: {
    entityCount: 5,
    fieldCount: 23,
    relationshipCount: 8,
    workflowCount: 3
  }
}

Phase Transitions

Automatic Progression

Phases advance based on:

• Completeness of information

• Confidence levels

• User confirmation

• Time in phase (avoid rushing)

Manual Override

Users can:

• Request to move forward: "Let's generate code"

• Ask to go back: "Wait, let me clarify"

• Reset: "Start over"

Transition Logic

function determinePhase(dsl: DSLContext): Phase {
  const { entities, relationships, readiness } = dsl
  
  if (readiness < 25) return 'discovering'
  if (readiness < 50) return 'clarifying'
  if (readiness < 75) return 'proposing'
  if (readiness < 90) return 'confirming'
  return 'building'
}

Phase-Specific Behaviors

Discovering Behavior

class DiscoveringPhase {
  async process(message: string) {
    // Extract high-level concepts
    const concepts = await extractConcepts(message)
    
    // Ask broad questions
    return {
      response: askBroadQuestions(concepts),
      suggestions: [
        "Tell me more about the users",
        "What's the main purpose?",
        "What problems does it solve?"
      ]
    }
  }
}

Clarifying Behavior

class ClarifyingPhase {
  async process(message: string, dsl: DSLContext) {
    // Identify gaps
    const gaps = findMissingInformation(dsl)
    
    // Ask specific questions
    return {
      response: askSpecificQuestions(gaps),
      suggestions: [
        "Add user authentication",
        "Define task priorities",
        "Specify user roles"
      ]
    }
  }
}

Readiness Calculation

Factors Contributing to Readiness

interface ReadinessFactors {
  entityCompleteness: number    // Do entities have fields?
  relationshipCoverage: number  // Are relationships defined?
  fieldSpecificity: number      // Are field types clear?
  businessLogic: number         // Are rules defined?
  authentication: number        // Is auth configured?
  userConfirmation: number      // Has user validated?
}

function calculateReadiness(factors: ReadinessFactors): number {
  const weights = {
    entityCompleteness: 0.25,
    relationshipCoverage: 0.20,
    fieldSpecificity: 0.15,
    businessLogic: 0.15,
    authentication: 0.10,
    userConfirmation: 0.15
  }
  
  return Object.entries(factors).reduce(
    (total, [key, value]) => total + value * weights[key],
    0
  ) * 100
}

Best Practices by Phase

For Users

#### During Discovering

• Start with the big picture

• Mention your industry/domain

• Describe the main problem

#### During Clarifying

• Answer questions thoroughly

• Provide specific examples

• Mention important constraints

#### During Proposing

• Review suggestions carefully

• Correct any misunderstandings

• Add missing features

#### During Confirming

• Double-check requirements

• Consider edge cases

• Confirm technical choices

#### During Building

• Choose appropriate generation options

• Review generated code

• Test incrementally

For Developers

#### Phase Indicators

// Add visual indicators
const phaseIndicators = {
  discovering: { icon: '🔵', color: 'blue' },
  clarifying: { icon: '🟡', color: 'yellow' },
  proposing: { icon: '🟣', color: 'purple' },
  confirming: { icon: '🟢', color: 'green' },
  building: { icon: '🔴', color: 'red' }
}

#### Phase Hooks

// React to phase changes
onPhaseChange((oldPhase, newPhase) => {
  // Update UI
  updateProgressBar()
  
  // Log analytics
  trackPhaseTransition(oldPhase, newPhase)
  
  // Notify user
  if (newPhase === 'building') {
    showNotification('Ready to generate code!')
  }
})

Common Patterns

Fast Track (Expert Users)

User: "Create a blog with User, Post (title, content, status: draft/published), 
Comment, Tag. Posts have many comments and tags. Users have many posts."

→ Jump to Proposing/Confirming phase

Exploratory (New Users)

User: "I want to build something for my business"
AI: "What kind of business?"
User: "Restaurant"
AI: "What do you need to manage?"

→ Gradual progression through all phases

Correction Loop

Phase: Proposing
User: "No, tasks shouldn't have multiple assignees"

→ Stay in Proposing, adjust model

Phase Analytics

Tracking Metrics

interface PhaseMetrics {
  timeInPhase: number
  messagesInPhase: number
  correctionsNeeded: number
  confidenceProgression: number[]
  userSatisfaction: number
}

Optimization Opportunities

• Phases taking too long → Improve questions

• Many corrections → Better initial extraction

• Low confidence → Request examples

Conversation Phases

The Five Phases Overview

Phase 1: Discovering (0-25%)

Purpose

Characteristics

Example Conversation

DSL State

Transition Triggers

Phase 2: Clarifying (25-50%)

Purpose

Characteristics

Example Conversation

DSL State

Transition Triggers

Phase 3: Proposing (50-75%)

Purpose

Characteristics

Example Conversation

DSL State

Transition Triggers

Phase 4: Confirming (75-90%)

Purpose

Characteristics

Example Conversation

DSL State

Transition Triggers

Phase 5: Building (90-100%)

Purpose

Characteristics

Example Conversation

DSL State

Phase Transitions

Automatic Progression

Manual Override

Transition Logic

Phase-Specific Behaviors

Discovering Behavior

Clarifying Behavior

Readiness Calculation

Factors Contributing to Readiness

Best Practices by Phase

For Users

For Developers

Common Patterns

Fast Track (Expert Users)

Exploratory (New Users)

Correction Loop

Phase Analytics

Tracking Metrics

Optimization Opportunities

Related Documentation