16 KiB
BMAD Intelligent Routing Engine
Overview
The Intelligent Routing Engine automatically analyzes user requests and routes them to the most appropriate persona(s) based on context, complexity, and required capabilities. It provides transparent decision-making with fallback mechanisms and continuous learning.
Core Components
Request Analysis Engine
Natural Language Processing Pipeline
```yaml nlp_pipeline: text_preprocessing: - "tokenization" - "stop_word_removal" - "lemmatization" - "named_entity_recognition"
feature_extraction: - "keyword_extraction" - "intent_classification" - "complexity_assessment" - "domain_identification"
context_analysis: - "project_phase_detection" - "technology_stack_identification" - "urgency_assessment" - "scope_evaluation"
#### Request Classification Framework
\```yaml
classification_categories:
primary_domains:
architecture: ["system_design", "technical_architecture", "scalability", "integration"]
development: ["coding", "implementation", "debugging", "testing"]
design: ["ui_ux", "visual_design", "user_experience", "prototyping"]
management: ["project_planning", "requirements", "coordination", "process"]
documentation: ["technical_writing", "api_docs", "guides", "procedures"]
quality: ["code_review", "performance", "security", "optimization"]
complexity_levels:
simple: ["single_persona", "straightforward_task", "well_defined_scope"]
moderate: ["multiple_considerations", "some_ambiguity", "cross_functional"]
complex: ["multiple_personas", "high_ambiguity", "enterprise_scope"]
expert: ["specialized_knowledge", "critical_decisions", "high_impact"]
urgency_indicators:
low: ["research", "planning", "documentation", "optimization"]
medium: ["feature_development", "enhancement", "review"]
high: ["bug_fix", "security_issue", "production_problem"]
critical: ["system_down", "data_breach", "compliance_violation"]
Persona Matching Algorithm
Capability-Based Matching
def calculate_persona_match_score(request_features, persona_capabilities):
"""
Calculate match score between request and persona capabilities
Returns score between 0.0 and 1.0
"""
# Primary capability matching (60% weight)
primary_match = calculate_primary_capability_match(
request_features.primary_domain,
persona_capabilities.primary_specializations
)
# Secondary capability matching (25% weight)
secondary_match = calculate_secondary_capability_match(
request_features.secondary_domains,
persona_capabilities.secondary_specializations
)
# Technology stack alignment (10% weight)
tech_match = calculate_technology_alignment(
request_features.technology_stack,
persona_capabilities.technology_expertise
)
# Complexity level compatibility (5% weight)
complexity_match = calculate_complexity_compatibility(
request_features.complexity_level,
persona_capabilities.complexity_handling
)
# Calculate weighted score
total_score = (
primary_match * 0.60 +
secondary_match * 0.25 +
tech_match * 0.10 +
complexity_match * 0.05
)
return min(total_score, 1.0)
Multi-Persona Coordination Logic
```yaml coordination_strategies: sequential_workflow: description: "Personas work in sequence with handoffs" use_cases: ["project_initiation", "feature_development", "documentation_creation"] coordination: "structured_handoff_protocols"
parallel_collaboration: description: "Multiple personas work simultaneously" use_cases: ["quality_validation", "comprehensive_review", "multi_domain_analysis"] coordination: "shared_context_and_synchronization"
hierarchical_consultation: description: "Primary persona with specialist consultations" use_cases: ["complex_troubleshooting", "enterprise_architecture", "security_review"] coordination: "primary_lead_with_expert_input"
dynamic_handoff: description: "Adaptive persona switching based on evolving needs" use_cases: ["exploratory_analysis", "iterative_development", "problem_solving"] coordination: "context_aware_transitions"
### Routing Decision Engine
#### Decision Tree Algorithm
\```yaml
routing_decision_tree:
root_analysis:
question: "What is the primary intent of the request?"
branches:
create_new: "creation_workflow"
analyze_existing: "analysis_workflow"
optimize_improve: "optimization_workflow"
troubleshoot_fix: "troubleshooting_workflow"
document_explain: "documentation_workflow"
creation_workflow:
question: "What type of artifact needs to be created?"
branches:
project_requirements: "analyst -> product_manager"
technical_architecture: "architect -> design_architect"
user_interface: "design_architect -> v0_ux_ui_architect"
documentation: "technical_documentation_architect"
analysis_workflow:
question: "What domain requires analysis?"
branches:
performance: "performance_optimization_specialist"
security: "security_integration_specialist"
code_quality: "polyglot_code_review_specialist"
enterprise_strategy: "enterprise_architecture_consultant"
optimization_workflow:
question: "What aspect needs optimization?"
branches:
system_performance: "performance_optimization_specialist -> architect"
security_posture: "security_integration_specialist -> architect"
code_quality: "polyglot_code_review_specialist"
workflow_process: "scrum_master -> product_owner"
troubleshooting_workflow:
question: "What is the complexity of the issue?"
branches:
simple_bug: "advanced_troubleshooting_specialist"
performance_issue: "performance_optimization_specialist -> advanced_troubleshooting_specialist"
security_incident: "security_integration_specialist -> advanced_troubleshooting_specialist"
system_failure: "advanced_troubleshooting_specialist -> architect -> enterprise_architecture_consultant"
Confidence Scoring System
```yaml confidence_metrics: high_confidence: threshold: "> 0.85" action: "direct_routing" validation: "minimal_user_confirmation"
medium_confidence: threshold: "0.65 - 0.85" action: "routing_with_alternatives" validation: "present_options_to_user"
low_confidence: threshold: "0.45 - 0.65" action: "guided_selection" validation: "interactive_clarification"
very_low_confidence: threshold: "< 0.45" action: "fallback_to_orchestrator" validation: "manual_persona_selection"
## Routing Algorithms
### Primary Routing Strategies
#### Intent-Based Routing
```python
def route_by_intent(request_text, context):
"""
Route based on detected user intent and context
"""
# Extract intent from request
intent = extract_intent(request_text)
# Analyze context for additional routing hints
context_hints = analyze_context(context)
# Map intent to persona capabilities
persona_candidates = map_intent_to_personas(intent, context_hints)
# Score and rank candidates
ranked_personas = score_and_rank_personas(persona_candidates, request_text)
# Apply confidence thresholds
routing_decision = apply_confidence_thresholds(ranked_personas)
return routing_decision
def extract_intent(request_text):
"""Extract primary intent from user request"""
intent_patterns = {
'create': ['create', 'build', 'develop', 'design', 'implement'],
'analyze': ['analyze', 'review', 'assess', 'evaluate', 'examine'],
'optimize': ['optimize', 'improve', 'enhance', 'refactor', 'tune'],
'troubleshoot': ['debug', 'fix', 'resolve', 'troubleshoot', 'diagnose'],
'document': ['document', 'explain', 'describe', 'guide', 'manual']
}
# Implementation details for intent extraction
return detected_intent
Technology Stack Routing
```yaml technology_routing_rules: frontend_technologies: react_typescript: primary: ["v0_ux_ui_architect", "design_architect"] secondary: ["performance_optimization_specialist", "polyglot_code_review_specialist"]
vue_angular:
primary: ["design_architect", "architect"]
secondary: ["cross_platform_integration_specialist"]
backend_technologies: nodejs: primary: ["architect", "cross_platform_integration_specialist"] secondary: ["performance_optimization_specialist", "security_integration_specialist"]
aspnet:
primary: ["architect", "enterprise_architecture_consultant"]
secondary: ["security_integration_specialist", "performance_optimization_specialist"]
python:
primary: ["architect", "performance_optimization_specialist"]
secondary: ["advanced_troubleshooting_specialist", "polyglot_code_review_specialist"]
infrastructure_technologies: cloud_platforms: primary: ["devops_documentation_specialist", "architect"] secondary: ["security_integration_specialist", "enterprise_architecture_consultant"]
containerization:
primary: ["devops_documentation_specialist", "cross_platform_integration_specialist"]
secondary: ["performance_optimization_specialist", "security_integration_specialist"]
#### Context-Aware Routing
\```yaml
context_routing_factors:
project_phase:
initiation:
primary_personas: ["analyst", "product_manager"]
workflow: "sequential"
planning:
primary_personas: ["architect", "design_architect"]
secondary_personas: ["enterprise_architecture_consultant", "security_integration_specialist"]
workflow: "parallel_consultation"
development:
primary_personas: ["v0_ux_ui_architect", "scrum_master"]
quality_personas: ["polyglot_code_review_specialist", "performance_optimization_specialist"]
workflow: "development_with_validation"
deployment:
primary_personas: ["devops_documentation_specialist"]
support_personas: ["security_integration_specialist", "advanced_troubleshooting_specialist"]
workflow: "deployment_with_monitoring"
urgency_level:
critical:
routing_strategy: "immediate_expert_routing"
personas: ["advanced_troubleshooting_specialist", "security_integration_specialist"]
escalation: ["enterprise_architecture_consultant", "architect"]
high:
routing_strategy: "fast_track_routing"
validation: "minimal"
normal:
routing_strategy: "standard_routing"
validation: "comprehensive"
low:
routing_strategy: "optimized_routing"
validation: "thorough_analysis"
Performance Optimization
Routing Performance Targets
```yaml performance_requirements: routing_decision_time: "< 500ms" persona_activation_time: "< 1000ms" context_analysis_time: "< 200ms" confidence_calculation_time: "< 100ms"
optimization_strategies: caching: request_patterns: "cache_common_routing_decisions" persona_capabilities: "cache_persona_metadata" context_analysis: "cache_context_analysis_results"
parallel_processing: capability_matching: "parallel_persona_scoring" context_analysis: "concurrent_context_processing" confidence_calculation: "parallel_confidence_scoring"
algorithmic_optimization: early_termination: "stop_analysis_when_high_confidence_reached" pruning: "eliminate_low_probability_personas_early" approximation: "use_approximation_for_non_critical_calculations"
### Continuous Learning System
\```yaml
learning_mechanisms:
feedback_collection:
user_satisfaction: "collect_user_feedback_on_routing_decisions"
routing_accuracy: "track_successful_vs_failed_routings"
performance_metrics: "monitor_routing_performance_continuously"
pattern_recognition:
successful_patterns: "identify_high_performing_routing_patterns"
failure_analysis: "analyze_failed_routing_decisions"
user_preferences: "learn_individual_user_routing_preferences"
model_improvement:
weight_adjustment: "adjust_scoring_weights_based_on_feedback"
threshold_optimization: "optimize_confidence_thresholds"
algorithm_refinement: "improve_routing_algorithms_based_on_data"
adaptation_strategies:
real_time_learning: "adapt_routing_decisions_based_on_immediate_feedback"
batch_learning: "periodic_model_updates_based_on_accumulated_data"
a_b_testing: "test_new_routing_strategies_with_subset_of_users"
Error Handling and Fallback
Robust Error Handling
```yaml error_scenarios: routing_failures: no_suitable_persona: action: "fallback_to_orchestrator_guidance" message: "Let me help you find the right expertise for your request"
multiple_equal_scores:
action: "present_options_to_user"
message: "I found multiple experts who could help. Which would you prefer?"
low_confidence_routing:
action: "guided_clarification"
message: "To route you to the best expert, could you clarify..."
performance_issues: routing_timeout: action: "fallback_to_simple_routing" timeout_threshold: "500ms"
persona_unavailable:
action: "suggest_alternative_persona"
alternatives: "ranked_by_capability_similarity"
system_overload:
action: "queue_request_with_estimated_wait_time"
priority: "based_on_urgency_level"
data_quality_issues: incomplete_request: action: "interactive_request_completion" guidance: "structured_question_prompts"
ambiguous_context:
action: "context_clarification_workflow"
clarification: "targeted_questions_based_on_ambiguity"
### Fallback Strategies
\```yaml
fallback_hierarchy:
level_1_intelligent_routing:
description: "Full AI-powered routing with high confidence"
success_rate: "> 85%"
level_2_guided_routing:
description: "AI suggestions with user confirmation"
fallback_trigger: "medium_confidence_or_user_preference"
level_3_manual_selection:
description: "User selects from recommended personas"
fallback_trigger: "low_confidence_or_routing_failure"
level_4_orchestrator_guidance:
description: "BMad orchestrator provides guidance"
fallback_trigger: "complete_routing_failure"
level_5_default_workflow:
description: "Standard workflow based on request type"
fallback_trigger: "system_unavailability"
Integration and Validation
Orchestrator Integration
```yaml integration_points: orchestrator_commands: "/route-analyze": "analyze_request_and_show_routing_decision" "/route-explain": "explain_why_specific_persona_was_selected" "/route-alternatives": "show_alternative_persona_options" "/route-feedback": "collect_feedback_on_routing_decision"
workflow_integration: pre_routing: "context_analysis_and_preparation" routing_decision: "intelligent_persona_selection" post_routing: "validation_and_feedback_collection"
quality_validation: routing_accuracy: "track_successful_routing_percentage" user_satisfaction: "measure_user_satisfaction_with_routing" performance_metrics: "monitor_routing_performance_continuously"
### Validation Framework
\```yaml
validation_metrics:
accuracy_metrics:
routing_success_rate: "> 90%"
user_satisfaction_score: "> 4.5/5"
first_attempt_success: "> 85%"
performance_metrics:
average_routing_time: "< 300ms"
95th_percentile_routing_time: "< 500ms"
system_availability: "> 99.5%"
quality_metrics:
routing_explanation_clarity: "> 4.0/5"
alternative_suggestion_relevance: "> 4.0/5"
fallback_effectiveness: "> 80%"
validation_methods:
automated_testing:
unit_tests: "test_individual_routing_components"
integration_tests: "test_end_to_end_routing_workflows"
performance_tests: "validate_routing_performance_requirements"
user_acceptance_testing:
scenario_testing: "test_routing_with_realistic_user_scenarios"
usability_testing: "validate_routing_user_experience"
feedback_collection: "gather_user_feedback_on_routing_decisions"
continuous_monitoring:
real_time_metrics: "monitor_routing_performance_in_production"
error_tracking: "track_and_analyze_routing_errors"
user_behavior_analysis: "analyze_user_interaction_patterns"