BMAD-METHOD/bmad-agent/tasks/handoff-orchestration-task.md

# Memory-Enhanced Handoff Orchestration Task

## Purpose
Facilitate structured, context-rich transitions between personas using memory insights to ensure optimal knowledge transfer and continuity.

## Memory-Enhanced Handoff Process

### 1. Pre-Handoff Analysis
```python
def analyze_handoff_readiness(source_persona, target_persona, current_context):
    # Search for similar handoff patterns
    handoff_memories = search_memory(
        f"handoff {source_persona} to {target_persona} {current_context.phase}",
        limit=5,
        threshold=0.7
    )
    
    # Analyze handoff quality factors
    readiness_assessment = {
        "artifacts_complete": check_required_artifacts(source_persona, current_context),
        "decisions_documented": validate_decision_logging(current_context),
        "blockers_resolved": assess_outstanding_issues(current_context),
        "context_clarity": evaluate_context_completeness(current_context),
        "historical_success_rate": calculate_handoff_success_rate(handoff_memories)
    }
    
    return readiness_assessment
```

### 2. Context Package Assembly
```python
def assemble_handoff_context(source_persona, target_persona, session_state):
    context_package = {
        # Immediate context
        "session_state": session_state,
        "recent_decisions": extract_recent_decisions(session_state),
        "active_concerns": identify_active_concerns(session_state),
        "completed_artifacts": list_completed_artifacts(session_state),
        
        # Memory-enhanced context
        "relevant_experiences": search_memory(
            f"{target_persona} working on {session_state.project_type} {session_state.phase}",
            limit=3,
            threshold=0.8
        ),
        "success_patterns": search_memory(
            f"successful handoff {source_persona} {target_persona}",
            limit=3,
            threshold=0.7
        ),
        "potential_pitfalls": search_memory(
            f"handoff problems {source_persona} {target_persona}",
            limit=2,
            threshold=0.7
        ),
        
        # Personalized context
        "user_preferences": search_memory(
            f"user-preference {target_persona} workflow",
            limit=2,
            threshold=0.9
        ),
        "working_style": extract_user_working_style(target_persona),
        
        # Proactive intelligence
        "likely_questions": predict_target_persona_questions(source_persona, target_persona, session_state),
        "recommended_focus": generate_focus_recommendations(target_persona, session_state),
        "optimization_opportunities": identify_optimization_opportunities(session_state)
    }
    
    return context_package
```

### 3. Structured Handoff Execution

#### Phase 1: Handoff Initiation
```markdown
# 🔄 Initiating Handoff: {Source Persona} → {Target Persona}

## Handoff Readiness Assessment
**Overall Readiness**: {readiness_score}/10

### ✅ Ready Components
- {ready_component_1}
- {ready_component_2}

### ⚠️ Attention Needed
- {attention_item_1}: {recommendation}
- {attention_item_2}: {recommendation}

### 📊 Historical Context
**Similar handoffs**: {success_rate}% success rate
**Typical duration**: ~{duration_estimate}
**Common success factors**: {success_factors}

## Proceed with handoff? (y/n)
```

#### Phase 2: Context Transfer
```markdown
# 📋 Context Transfer Package

## Immediate Situation
**Project Phase**: {current_phase}
**Last Completed**: {last_major_task}
**Current Priority**: {priority_focus}

## Key Decisions Made
{decision_log_summary}

## Outstanding Items
**Blockers**: {active_blockers}
**Pending Decisions**: {pending_decisions}
**Follow-up Required**: {follow_up_items}

## Memory-Enhanced Context
### 🎯 Relevant Past Experience
**Similar situations you've handled**:
- {relevant_memory_1}
- {relevant_memory_2}

### ✅ What Usually Works
Based on {n} similar handoffs:
- {success_pattern_1}
- {success_pattern_2}

### ⚠️ Potential Pitfalls
Watch out for:
- {pitfall_1}: {mitigation_strategy}
- {pitfall_2}: {mitigation_strategy}

## Your Working Style Preferences
**You typically prefer**: {user_preference_1}
**You're most effective when**: {optimal_condition_1}
**Consider**: {personalized_suggestion}

## Likely Questions & Answers
**Q**: {predicted_question_1}
**A**: {prepared_answer_1}

**Q**: {predicted_question_2}
**A**: {prepared_answer_2}

## Recommended Focus Areas
🎯 **Primary Focus**: {primary_recommendation}
💡 **Optimization Opportunity**: {efficiency_suggestion}
⏱️ **Time-Sensitive Items**: {urgent_items}
```

#### Phase 3: Target Persona Activation
```python
def activate_target_persona_with_context(target_persona, context_package):
    # Load target persona
    persona_definition = load_persona(target_persona)
    
    # Apply memory-enhanced customizations
    persona_customizations = extract_customizations(context_package.user_preferences)
    
    # Create enhanced activation prompt
    activation_prompt = f"""
    You are now {persona_definition.role_name}.
    
    CONTEXT BRIEFING:
    {context_package.immediate_context}
    
    MEMORY INSIGHTS:
    {context_package.relevant_experiences}
    
    YOUR HISTORICAL SUCCESS PATTERNS:
    {context_package.success_patterns}
    
    WATCH OUT FOR:
    {context_package.potential_pitfalls}
    
    PERSONALIZED FOR YOUR STYLE:
    {context_package.user_preferences}
    
    RECOMMENDED IMMEDIATE ACTIONS:
    {context_package.recommended_focus}
    """
    
    return activation_prompt
```

### 4. Handoff Quality Validation
```python
def validate_handoff_quality(handoff_session):
    validation_checks = [
        {
            "check": "context_understanding",
            "test": lambda: verify_target_persona_understanding(handoff_session),
            "required": True
        },
        {
            "check": "artifact_accessibility", 
            "test": lambda: verify_artifact_access(handoff_session),
            "required": True
        },
        {
            "check": "decision_continuity",
            "test": lambda: verify_decision_awareness(handoff_session),
            "required": True
        },
        {
            "check": "blocker_clarity",
            "test": lambda: verify_blocker_understanding(handoff_session),
            "required": True
        },
        {
            "check": "next_steps_clear",
            "test": lambda: verify_action_clarity(handoff_session),
            "required": False
        }
    ]
    
    results = []
    for check in validation_checks:
        result = {
            "check_name": check["check"],
            "passed": check["test"](),
            "required": check["required"]
        }
        results.append(result)
    
    return results
```

#### Validation Interaction
```markdown
# ✅ Handoff Validation

Before we complete the handoff, let me verify understanding:

## Quick Validation Questions
1. **Context Check**: Can you briefly summarize the current project state and your immediate priorities?

2. **Decision Awareness**: What are the key decisions that have been made that will impact your work?

3. **Blocker Identification**: Are there any current blockers or dependencies you need to address?

4. **Next Steps**: What do you see as your logical next actions?

## Memory Integration Check
5. **Success Pattern**: Based on the provided context, which approach do you plan to take and why?

6. **Pitfall Awareness**: What potential issues will you watch out for based on the shared insights?

---
✅ **Validation Complete**: All required understanding confirmed
⚠️ **Needs Clarification**: {specific_areas_needing_attention}
```

### 5. Post-Handoff Memory Creation
```python
def create_handoff_memory(handoff_session):
    handoff_memory = {
        "type": "handoff",
        "source_persona": handoff_session.source_persona,
        "target_persona": handoff_session.target_persona,
        "project_phase": handoff_session.project_phase,
        "context_quality": assess_context_quality(handoff_session),
        "handoff_duration": handoff_session.duration_minutes,
        "validation_score": calculate_validation_score(handoff_session.validation_results),
        "success_factors": extract_success_factors(handoff_session),
        "improvement_areas": identify_improvement_areas(handoff_session),
        "user_satisfaction": handoff_session.user_satisfaction_rating,
        "artifacts_transferred": handoff_session.artifacts_list,
        "decisions_transferred": handoff_session.decisions_list,
        "follow_up_effectiveness": "to_be_measured",  # Updated later
        "reusable_insights": extract_reusable_insights(handoff_session)
    }
    
    add_memories(
        content=json.dumps(handoff_memory),
        tags=generate_handoff_tags(handoff_memory),
        metadata={
            "type": "handoff",
            "quality_score": handoff_memory.validation_score,
            "reusability": "high"
        }
    )
```

### 6. Handoff Success Tracking
```python
def schedule_handoff_followup(handoff_memory_id):
    # Schedule follow-up assessment
    followup_schedule = [
        {
            "timeframe": "1_hour",
            "check": "immediate_productivity",
            "questions": [
                "Was the target persona able to start work immediately?",
                "Were any critical information gaps discovered?",
                "Did the handoff context prove accurate and useful?"
            ]
        },
        {
            "timeframe": "24_hours", 
            "check": "effectiveness_validation",
            "questions": [
                "How effective was the memory-enhanced context?",
                "Were the predicted questions/issues accurate?",
                "What additional context would have been helpful?"
            ]
        },
        {
            "timeframe": "1_week",
            "check": "long_term_impact",
            "questions": [
                "Did the handoff contribute to overall project success?",
                "Were there any downstream issues from context gaps?",
                "What patterns can be learned for future handoffs?"
            ]
        }
    ]
    
    for followup in followup_schedule:
        schedule_memory_update(handoff_memory_id, followup)
```

## Handoff Optimization Patterns

### High-Quality Handoff Indicators
```yaml
quality_indicators:
  context_completeness:
    - decision_log_current: true
    - artifacts_documented: true
    - blockers_identified: true
    - next_steps_clear: true
    
  memory_enhancement:
    - relevant_experiences_provided: true
    - success_patterns_shared: true
    - pitfalls_identified: true
    - personalization_applied: true
    
  validation_success:
    - understanding_confirmed: true
    - questions_answered: true
    - confidence_high: true
    - immediate_productivity: true
```

### Common Handoff Anti-Patterns
```yaml
anti_patterns:
  context_gaps:
    - "incomplete_decision_documentation"
    - "missing_artifact_references"
    - "unresolved_blockers_not_communicated"
    - "implicit_assumptions_not_shared"
    
  memory_underutilization:
    - "ignoring_historical_patterns"
    - "not_sharing_relevant_experiences"
    - "missing_personalization_opportunities"
    - "overlooking_predictable_issues"
    
  validation_failures:
    - "skipping_understanding_verification"
    - "assuming_context_transfer_success"
    - "not_addressing_confusion_immediately"
    - "incomplete_next_steps_clarity"
```

### Handoff Optimization Strategies
```python
def optimize_future_handoffs(handoff_analysis):
    optimizations = []
    
    # Analyze handoff success patterns
    successful_handoffs = filter_successful_handoffs(handoff_analysis)
    failed_handoffs = filter_failed_handoffs(handoff_analysis)
    
    # Extract optimization opportunities
    for success in successful_handoffs:
        optimizations.append({
            "type": "success_pattern",
            "pattern": success.key_success_factors,
            "applicability": assess_pattern_applicability(success),
            "confidence": success.success_rate
        })
    
    for failure in failed_handoffs:
        optimizations.append({
            "type": "failure_prevention",
            "issue": failure.root_cause,
            "prevention": failure.prevention_strategy,
            "early_detection": failure.warning_signs
        })
    
    return optimizations
```

## Integration with BMAD Commands

### Enhanced Handoff Commands
```bash
# Basic handoff command with memory enhancement
/handoff <target_persona>              # Memory-enhanced structured handoff

# Advanced handoff options
/handoff <target_persona> --quick      # Streamlined handoff for simple transitions
/handoff <target_persona> --detailed   # Comprehensive handoff with full context
/handoff <target_persona> --validate   # Extra validation steps for critical transitions

# Handoff analysis and optimization
/handoff-analyze                       # Analyze recent handoff patterns
/handoff-optimize                      # Get suggestions for improving handoffs
/handoff-history <persona_pair>        # Show history between specific personas
```

### Command Implementation Examples
```python
def handle_handoff_command(args, current_context):
    target_persona = args.target_persona
    mode = args.mode or "standard"
    
    if mode == "quick":
        return execute_quick_handoff(target_persona, current_context)
    elif mode == "detailed":
        return execute_detailed_handoff(target_persona, current_context)
    elif mode == "validate":
        return execute_validated_handoff(target_persona, current_context)
    else:
        return execute_standard_handoff(target_persona, current_context)
```

This memory-enhanced handoff system ensures that context transitions between personas are smooth, information-rich, and continuously improving based on past experiences.