BMAD-METHOD/bmad-agent/orchestrator/request-analysis-system.md

# BMAD Request Analysis System

## Overview

The Request Analysis System provides comprehensive natural language processing and context analysis capabilities to understand user requests and extract relevant information for intelligent persona routing.

## Core Analysis Components

###  Natural Language Processing Pipeline

#### Text Preprocessing
```python
def preprocess_request(request_text):
    """
    Comprehensive text preprocessing for request analysis
    """
    
    # Basic text cleaning
    cleaned_text = clean_text(request_text)
    
    # Tokenization with context preservation
    tokens = advanced_tokenize(cleaned_text)
    
    # Named Entity Recognition
    entities = extract_entities(tokens)
    
    # Part-of-speech tagging
    pos_tags = pos_tag(tokens)
    
    # Dependency parsing for relationship extraction
    dependencies = parse_dependencies(tokens)
    
    return {
        'cleaned_text': cleaned_text,
        'tokens': tokens,
        'entities': entities,
        'pos_tags': pos_tags,
        'dependencies': dependencies
    }

def extract_entities(tokens):
    """Extract domain-specific entities from request"""
    entity_patterns = {
        'technologies': ['react', 'typescript', 'nodejs', 'python', 'aspnet', 'docker', 'kubernetes'],
        'actions': ['create', 'build', 'optimize', 'debug', 'review', 'analyze', 'document'],
        'artifacts': ['api', 'component', 'architecture', 'database', 'documentation', 'test'],
        'domains': ['frontend', 'backend', 'security', 'performance', 'deployment', 'integration']
    }
    
    # Implementation for entity extraction
    return extracted_entities
```

#### Intent Classification Framework
\```yaml
intent_classification:
  primary_intents:
    creation:
      keywords: ["create", "build", "develop", "implement", "design", "generate"]
      confidence_boosters: ["new", "from scratch", "initial", "prototype"]
      examples:
        - "Create a new React component for user authentication"
        - "Build a REST API for user management"
        - "Design a microservices architecture"
        
    analysis:
      keywords: ["analyze", "review", "assess", "evaluate", "examine", "investigate"]
      confidence_boosters: ["existing", "current", "performance", "security"]
      examples:
        - "Analyze the performance of our current system"
        - "Review the security of our API endpoints"
        - "Assess the scalability of our architecture"
        
    optimization:
      keywords: ["optimize", "improve", "enhance", "refactor", "tune", "upgrade"]
      confidence_boosters: ["better", "faster", "efficient", "scalable"]
      examples:
        - "Optimize the performance of our React application"
        - "Improve the security of our authentication system"
        - "Enhance the user experience of our dashboard"
        
    troubleshooting:
      keywords: ["debug", "fix", "resolve", "troubleshoot", "diagnose", "solve"]
      confidence_boosters: ["issue", "problem", "error", "bug", "failure"]
      examples:
        - "Debug a memory leak in our Node.js application"
        - "Fix authentication issues in our React app"
        - "Resolve performance problems in our database"
        
    documentation:
      keywords: ["document", "explain", "describe", "guide", "manual", "specification"]
      confidence_boosters: ["how to", "step by step", "tutorial", "reference"]
      examples:
        - "Document our API endpoints and usage"
        - "Create a deployment guide for our application"
        - "Explain our system architecture to new developers"
```

###  Complexity Assessment Engine

#### Multi-Dimensional Complexity Analysis
```python
def assess_request_complexity(request_features):
    """
    Assess request complexity across multiple dimensions
    """
    
    # Technical complexity assessment
    technical_complexity = assess_technical_complexity(request_features)
    
    # Scope complexity assessment
    scope_complexity = assess_scope_complexity(request_features)
    
    # Domain complexity assessment
    domain_complexity = assess_domain_complexity(request_features)
    
    # Stakeholder complexity assessment
    stakeholder_complexity = assess_stakeholder_complexity(request_features)
    
    # Calculate overall complexity score
    overall_complexity = calculate_weighted_complexity(
        technical_complexity,
        scope_complexity,
        domain_complexity,
        stakeholder_complexity
    )
    
    return {
        'overall_complexity': overall_complexity,
        'technical_complexity': technical_complexity,
        'scope_complexity': scope_complexity,
        'domain_complexity': domain_complexity,
        'stakeholder_complexity': stakeholder_complexity,
        'complexity_level': map_to_complexity_level(overall_complexity)
    }

def assess_technical_complexity(features):
    """Assess technical complexity based on various factors"""
    complexity_indicators = {
        'technology_stack_size': len(features.technologies),
        'integration_points': count_integration_requirements(features),
        'performance_requirements': assess_performance_requirements(features),
        'security_requirements': assess_security_requirements(features),
        'scalability_requirements': assess_scalability_requirements(features)
    }
    
    return calculate_technical_complexity_score(complexity_indicators)
```

#### Complexity Level Mapping
\```yaml
complexity_levels:
  simple:
    score_range: "0.0 - 0.3"
    characteristics:
      - "Single technology stack"
      - "Well-defined requirements"
      - "Limited scope"
      - "Standard implementation patterns"
    recommended_personas: ["scrum_master", "product_owner", "v0_ux_ui_architect"]
    
  moderate:
    score_range: "0.3 - 0.6"
    characteristics:
      - "Multiple technologies involved"
      - "Some ambiguity in requirements"
      - "Cross-functional considerations"
      - "Integration requirements"
    recommended_personas: ["analyst", "product_manager", "design_architect", "architect"]
    
  complex:
    score_range: "0.6 - 0.8"
    characteristics:
      - "Multiple domains and technologies"
      - "High ambiguity or uncertainty"
      - "Significant integration challenges"
      - "Performance or security critical"
    recommended_personas: ["architect", "enterprise_architecture_consultant", "security_integration_specialist"]
    
  expert:
    score_range: "0.8 - 1.0"
    characteristics:
      - "Highly specialized knowledge required"
      - "Critical business impact"
      - "Complex technical challenges"
      - "Enterprise-scale considerations"
    recommended_personas: ["enterprise_architecture_consultant", "advanced_troubleshooting_specialist", "performance_optimization_specialist"]
```

###  Technology Stack Detection

#### Technology Pattern Recognition
\```yaml
technology_patterns:
  frontend_frameworks:
    react:
      keywords: ["react", "jsx", "tsx", "react-dom", "create-react-app"]
      file_extensions: [".jsx", ".tsx"]
      package_indicators: ["react", "@types/react"]
      
    vue:
      keywords: ["vue", "vuejs", "vue-cli", "nuxt"]
      file_extensions: [".vue"]
      package_indicators: ["vue", "@vue/cli"]
      
    angular:
      keywords: ["angular", "ng", "typescript", "angular-cli"]
      file_extensions: [".component.ts", ".service.ts"]
      package_indicators: ["@angular/core", "@angular/cli"]
      
  backend_frameworks:
    nodejs:
      keywords: ["node", "nodejs", "express", "npm", "yarn"]
      file_indicators: ["package.json", "server.js", "app.js"]
      package_indicators: ["express", "fastify", "koa"]
      
    aspnet:
      keywords: ["asp.net", "dotnet", "c#", "mvc", "web api"]
      file_extensions: [".cs", ".csproj"]
      package_indicators: ["Microsoft.AspNetCore"]
      
    python:
      keywords: ["python", "django", "flask", "fastapi", "pip"]
      file_extensions: [".py"]
      package_indicators: ["django", "flask", "fastapi"]
      
  databases:
    sql_databases:
      keywords: ["sql", "mysql", "postgresql", "sql server", "oracle"]
      file_extensions: [".sql"]
      
    nosql_databases:
      keywords: ["mongodb", "redis", "elasticsearch", "dynamodb"]
      
  cloud_platforms:
    aws:
      keywords: ["aws", "amazon", "ec2", "s3", "lambda", "cloudformation"]
      
    azure:
      keywords: ["azure", "microsoft", "arm template", "azure functions"]
      
    gcp:
      keywords: ["google cloud", "gcp", "compute engine", "cloud functions"]
```

#### Technology Expertise Mapping
```python
def map_technologies_to_personas(detected_technologies):
    """
    Map detected technologies to persona expertise levels
    """
    
    persona_technology_matrix = {
        'v0_ux_ui_architect': {
            'primary': ['react', 'typescript', 'javascript', 'css', 'html'],
            'secondary': ['vue', 'angular', 'sass', 'tailwind']
        },
        'architect': {
            'primary': ['nodejs', 'python', 'aspnet', 'microservices', 'api_design'],
            'secondary': ['react', 'databases', 'cloud_platforms']
        },
        'performance_optimization_specialist': {
            'primary': ['performance_monitoring', 'caching', 'database_optimization'],
            'secondary': ['nodejs', 'python', 'react', 'aspnet']
        },
        'security_integration_specialist': {
            'primary': ['security_frameworks', 'authentication', 'encryption'],
            'secondary': ['aspnet', 'nodejs', 'cloud_security']
        },
        'devops_documentation_specialist': {
            'primary': ['docker', 'kubernetes', 'ci_cd', 'cloud_platforms'],
            'secondary': ['monitoring', 'logging', 'infrastructure_as_code']
        }
    }
    
    # Calculate persona scores based on technology overlap
    persona_scores = {}
    for persona, expertise in persona_technology_matrix.items():
        score = calculate_technology_overlap_score(
            detected_technologies, 
            expertise
        )
        persona_scores[persona] = score
    
    return persona_scores
```

###  Context Analysis Framework

#### Project Phase Detection
\```yaml
project_phases:
  initiation:
    indicators: ["new project", "starting", "initial", "brainstorm", "research"]
    artifacts: ["project brief", "requirements", "research findings"]
    recommended_workflow: ["analyst", "product_manager"]
    
  planning:
    indicators: ["plan", "design", "architecture", "strategy", "roadmap"]
    artifacts: ["prd", "architecture document", "design system"]
    recommended_workflow: ["architect", "design_architect", "enterprise_architecture_consultant"]
    
  development:
    indicators: ["implement", "code", "build", "develop", "create"]
    artifacts: ["components", "apis", "features", "tests"]
    recommended_workflow: ["v0_ux_ui_architect", "scrum_master", "product_owner"]
    
  testing:
    indicators: ["test", "validate", "verify", "quality", "review"]
    artifacts: ["test cases", "quality reports", "code reviews"]
    recommended_workflow: ["polyglot_code_review_specialist", "performance_optimization_specialist"]
    
  deployment:
    indicators: ["deploy", "release", "production", "launch", "go-live"]
    artifacts: ["deployment guides", "runbooks", "monitoring"]
    recommended_workflow: ["devops_documentation_specialist", "security_integration_specialist"]
    
  maintenance:
    indicators: ["maintain", "support", "monitor", "optimize", "troubleshoot"]
    artifacts: ["monitoring dashboards", "incident reports", "optimization plans"]
    recommended_workflow: ["advanced_troubleshooting_specialist", "performance_optimization_specialist"]
```

#### Urgency Assessment
```python
def assess_request_urgency(request_text, context):
    """
    Assess the urgency level of a request based on various indicators
    """
    
    urgency_indicators = {
        'critical': {
            'keywords': ['critical', 'urgent', 'emergency', 'down', 'broken', 'security breach'],
            'context_indicators': ['production_issue', 'system_failure', 'data_loss'],
            'score_weight': 1.0
        },
        'high': {
            'keywords': ['asap', 'quickly', 'soon', 'priority', 'important', 'blocking'],
            'context_indicators': ['deadline_approaching', 'stakeholder_pressure'],
            'score_weight': 0.8
        },
        'medium': {
            'keywords': ['needed', 'required', 'should', 'would like', 'planning'],
            'context_indicators': ['scheduled_work', 'planned_feature'],
            'score_weight': 0.5
        },
        'low': {
            'keywords': ['eventually', 'when possible', 'nice to have', 'future'],
            'context_indicators': ['research', 'exploration', 'optimization'],
            'score_weight': 0.2
        }
    }
    
    # Calculate urgency score
    urgency_score = calculate_urgency_score(request_text, context, urgency_indicators)
    
    # Map score to urgency level
    urgency_level = map_score_to_urgency_level(urgency_score)
    
    return {
        'urgency_level': urgency_level,
        'urgency_score': urgency_score,
        'routing_priority': get_routing_priority(urgency_level)
    }
```

## Advanced Analysis Features

###  Semantic Understanding
\```yaml
semantic_analysis:
  relationship_extraction:
    - "subject_verb_object_relationships"
    - "dependency_relationships"
    - "causal_relationships"
    - "temporal_relationships"
    
  concept_mapping:
    - "domain_concept_identification"
    - "technical_concept_mapping"
    - "business_concept_extraction"
    - "process_concept_recognition"
    
  context_inference:
    - "implicit_requirement_inference"
    - "stakeholder_inference"
    - "constraint_inference"
    - "goal_inference"
```

###  Continuous Learning Integration
```python
def update_analysis_models(feedback_data):
    """
    Update analysis models based on user feedback and routing success
    """
    
    # Update intent classification model
    update_intent_classifier(feedback_data.intent_feedback)
    
    # Update complexity assessment model
    update_complexity_model(feedback_data.complexity_feedback)
    
    # Update technology detection patterns
    update_technology_patterns(feedback_data.technology_feedback)
    
    # Update urgency assessment model
    update_urgency_model(feedback_data.urgency_feedback)
    
    # Retrain models with new data
    retrain_analysis_models()
    
    return {
        'models_updated': True,
        'performance_improvement': calculate_performance_improvement(),
        'next_update_scheduled': schedule_next_update()
    }
```

###  Performance Monitoring
\```yaml
analysis_performance_metrics:
  accuracy_metrics:
    intent_classification_accuracy: "> 92%"
    complexity_assessment_accuracy: "> 88%"
    technology_detection_accuracy: "> 95%"
    urgency_assessment_accuracy: "> 85%"
    
  performance_metrics:
    analysis_processing_time: "< 200ms"
    memory_usage_per_analysis: "< 10MB"
    concurrent_analysis_capacity: "> 100 requests/second"
    
  quality_metrics:
    false_positive_rate: "< 5%"
    false_negative_rate: "< 8%"
    confidence_calibration: "> 90%"
```