488 lines
16 KiB
Markdown
488 lines
16 KiB
Markdown
# 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
|
|
```python
|
|
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"
|
|
```
|