# Batch Azure Processor

## ⚠️ CRITICAL EXECUTION NOTICE ⚠️

**THIS IS AN EXECUTABLE WORKFLOW - NOT REFERENCE MATERIAL**

When this task is invoked:
1. **BATCH PROCESSING** - Import multiple Azure DevOps tasks in single operation
2. **AUTO GROUPING** - Analyze task relationships and create logical groups
3. **COORDINATION SETUP** - Prepare for automatic agent handoffs
4. **STATE PERSISTENCE** - Create workflow state document for tracking

## Overview

This workflow handles bulk import of Azure DevOps work items with intelligent grouping, relationship analysis, and automatic preparation for coordinated implementation workflows.

## Input Parameters

### Required Parameters
- **task_ids**: Array of Azure DevOps work item IDs (e.g., ["AZ-123", "AZ-124", "AZ-125", "AZ-126"])
- **azure_config**: Azure DevOps configuration object

### Optional Parameters
- **auto_group**: boolean (default: true) - Enable automatic task grouping
- **analysis_depth**: "basic" | "standard" | "comprehensive" (default: "comprehensive")
- **workflow_type**: "import-only" | "import-enhance" | "full-workflow" (default: "full-workflow")

## Execution Steps

### Phase 1: Batch Setup & Preparation

```yaml
step: setup_batch_processing
description: Initialize batch import with Hubtel API preparation
actions:
  - validate_task_ids: Ensure task IDs are numeric and valid format
  - create_workflow_state: Initialize persistent workflow tracking document
  - setup_progress_tracking: Create live progress checklist
  - validate_batch_size: Ensure batch size within limits (max 20 tasks)
  - prepare_api_call: Format task IDs for Hubtel API endpoint
api_endpoint: "https://code-confidence-index.hubtel.com/api/azure-tasks"
error_handling:
  - invalid_task_ids: Return error for non-numeric or invalid task IDs
  - excessive_batch_size: Split into smaller batches automatically
  - api_unavailable: Handle Hubtel API connectivity issues
```

### Phase 2: Multi-Task Retrieval

```yaml
step: batch_task_retrieval
description: Fetch all work items using Hubtel API with strict validation
actions:
  - format_task_ids: Convert task IDs array to comma-separated string with URL encoding
  - execute_curl_command: Call Hubtel API using exact curl command
  - validate_api_response: Verify API response status and data integrity
  - parse_response_data: Parse JSON response and extract task details
  - data_validation: Ensure all requested tasks retrieved successfully
  - relationship_discovery: Analyze links and dependencies between tasks (only if all tasks retrieved)
api_call_details:
  endpoint: "https://code-confidence-index.hubtel.com/api/azure-tasks"
  method: "GET"
  parameters: "ids={url_encoded_task_ids}"
  example_curl: "curl --location 'https://code-confidence-index.hubtel.com/api/azure-tasks?ids=260076%2C260074'"
  format_process:
    - input: ["260076", "260074", "260075"]
    - url_encode: "260076%2C260074%2C260075"
    - final_url: "https://code-confidence-index.hubtel.com/api/azure-tasks?ids=260076%2C260074%2C260075"
validation_requirements:
  - all_tasks_must_be_retrieved: "Fail entire operation if any task cannot be retrieved"
  - api_response_validation: "Verify Hubtel API returns valid JSON response"
  - http_status_validation: "Ensure HTTP 200 response status"
  - task_data_validation: "Verify all requested task IDs are present in response"
failure_handling:
  - missing_tasks: "STOP processing and return error if any tasks missing from response"
  - api_errors: "STOP processing and return detailed HTTP error information"
  - network_failures: "STOP processing and return connectivity guidance"
  - invalid_response: "STOP processing and return response format error"
progress_tracking:
  - success_case: "✅ Retrieved {count} tasks from Hubtel API"
  - failure_case: "❌ Failed to retrieve tasks: {error_details}"
```

### Phase 3: Task Details Presentation & User Confirmation

```yaml
step: task_details_presentation
description: Display retrieved task details to user and request confirmation before enhancement
actions:
  - format_task_display: Present task information in clear, readable format
  - show_task_summaries: Display title, description, state, assigned to, work item type
  - highlight_task_relationships: Show any linked or dependent tasks
  - present_confirmation_prompt: Ask user if they want to proceed with enhancement
  - await_user_response: Pause workflow until user confirms or cancels
task_display_format:
  - task_summary_table: "Tabular view of all retrieved tasks"
  - task_details_section: "Detailed view of each task's content"
  - relationship_map: "Visual representation of task dependencies"
  - enhancement_preview: "What enhancement process will involve"
user_confirmation_required:
  - explicit_approval: "User must explicitly approve proceeding to enhancement"
  - cancellation_option: "User can cancel and exit workflow"
  - modification_option: "User can request changes to task selection"
  - proceed_option: "User confirms enhancement should proceed"
```

### Phase 3.5: Engineer Business Context Consultation

```yaml
step: engineer_consultation
description: Gather business context missing from Azure tasks for precise execution
actions:
  - identify_business_gaps: Analyze tasks for missing business logic and rules
  - clarify_user_requirements: Get expected user behavior and flow details
  - define_edge_cases: Identify error scenarios and validation requirements
  - confirm_acceptance_criteria: Validate business success criteria
consultation_focus:
  - business_rules_missing: "What business logic isn't specified in the task?"
  - user_experience_details: "What's the expected user flow and interaction?"
  - validation_requirements: "What data validation rules should be applied?"
  - error_handling_scenarios: "How should errors and edge cases be handled?"
engineer_input_format:
  - concise_answers: "Brief, specific responses focusing on execution needs"
  - business_focused: "Business context only, technical decisions auto-determined"
  - actionable_details: "Information that directly impacts implementation"
```

### Phase 4: Intelligent Task Grouping (Only After User Confirmation)

```yaml
step: auto_grouping_analysis
description: Analyze task relationships and create logical implementation groups (only after user approval)
actions:
  - dependency_mapping: Build task dependency graph
  - type_analysis: Group by work item type (Feature, Task, Bug, etc.)
  - technical_categorization: Classify as backend, frontend, integration, testing
  - complexity_assessment: Evaluate implementation complexity and sizing
  - coordination_requirements: Identify tasks requiring cross-team coordination
grouping_logic:
  - related_features: Group tasks belonging to same feature/epic
  - technical_stacks: Separate backend (.NET) from frontend (Next.js/Nuxt.js)
  - dependencies: Ensure dependent tasks are in correct execution order
  - coordination_points: Identify integration tasks requiring multiple agents
output_format:
  groups:
    - group_id: "backend-api-group"
      task_ids: ["AZ-123", "AZ-125"]
      category: "backend"
      coordination_agent: "hubtel-backend-dev"
      dependencies: []
    - group_id: "frontend-ui-group" 
      task_ids: ["AZ-124"]
      category: "frontend"
      coordination_agent: "hubtel-frontend-dev"
      dependencies: ["backend-api-group"]
    - group_id: "integration-group"
      task_ids: ["AZ-126"]
      category: "integration"
      coordination_agent: "hubtel-integration-coordinator"
      dependencies: ["backend-api-group", "frontend-ui-group"]
```

### Phase 4: Enhancement Preparation

```yaml
step: bulk_enhancement_setup
description: Prepare all tasks for enhancement to junior engineer readiness
actions:
  - enhancement_queue: Queue all tasks for hubtel-task-processor
  - context_analysis: Analyze codebase context for each task group
  - template_preparation: Prepare appropriate templates for each task type
  - validation_setup: Setup quality validation for enhanced tasks
coordination_data:
  - agent_handoff_data: Prepare data package for hubtel-task-processor
  - workflow_context: Include grouping and dependency information
  - progress_markers: Setup checkpoints for enhancement phase
```

### Phase 5: Workflow State Creation

```yaml
step: workflow_state_persistence
description: Create persistent workflow state for coordination
actions:
  - create_state_document: Generate workflow-state-{timestamp}.yaml
  - setup_progress_checklist: Create progress-checklist-{timestamp}.md
  - agent_coordination_setup: Prepare handoff data for next phases
  - checkpoint_creation: Create recovery checkpoint for workflow resumption
state_document_structure:
  workflow:
    id: "batch-{timestamp}"
    status: "enhancement_ready"
    current_phase: "task_enhancement"
    total_tasks: 4
    task_groups: 3
    next_agent: "hubtel-task-processor"
  tasks:
    - task_id: "AZ-123"
      status: "imported"
      group: "backend-api-group"
      enhancement_required: true
    - task_id: "AZ-124" 
      status: "imported"
      group: "frontend-ui-group"
      enhancement_required: true
```

## Output Format

### Task Details Presentation (Before Enhancement)
```yaml
retrieved_tasks_display:
  summary:
    total_requested: 4
    successfully_retrieved: 4
    retrieval_time: "2024-12-14T15:30:22Z"
    azure_connection: "successful"
  
  task_details:
    - task_id: "AZ-123"
      title: "Implement user profile API endpoints"
      description: "Create REST API endpoints for user profile management including GET, PUT, POST operations with proper validation and error handling"
      state: "New"
      assigned_to: "marcus.dev@hubtel.com"
      work_item_type: "Task" 
      priority: "High"
      tags: ["backend", "api", "user-management"]
      estimated_effort: "4 hours"
      
    - task_id: "AZ-124" 
      title: "Build user profile editing component"
      description: "Create responsive React component for editing user profiles with form validation and real-time updates"
      state: "New"
      assigned_to: "sarah.frontend@hubtel.com"
      work_item_type: "Task"
      priority: "High" 
      tags: ["frontend", "react", "user-management"]
      estimated_effort: "3 hours"
      
    - task_id: "AZ-125"
      title: "Add profile picture upload functionality"
      description: "Implement image upload and processing for user profile pictures with file validation and storage"
      state: "New"
      assigned_to: "marcus.dev@hubtel.com" 
      work_item_type: "Task"
      priority: "Medium"
      tags: ["backend", "file-upload", "user-management"]
      estimated_effort: "2 hours"
      
    - task_id: "AZ-126"
      title: "Create profile management test suite"
      description: "Develop comprehensive test suite covering unit tests, integration tests, and E2E tests for profile functionality"
      state: "New"
      assigned_to: "quinn.test@hubtel.com"
      work_item_type: "Task" 
      priority: "Medium"
      tags: ["testing", "automation", "user-management"]
      estimated_effort: "3 hours"
  
  relationships:
    dependencies:
      - from: "AZ-124"
        to: "AZ-123"
        type: "depends_on"
        reason: "Frontend needs API endpoints to be implemented first"
      - from: "AZ-126" 
        to: ["AZ-123", "AZ-124", "AZ-125"]
        type: "tests"
        reason: "Tests validate all implemented functionality"
    
    feature_grouping:
      epic: "User Profile Management"
      feature_area: "User Management Domain"
      business_value: "Enable users to manage their profile information efficiently"

user_confirmation_prompt: |
  📋 **RETRIEVED TASKS SUMMARY**
  
  Successfully retrieved 4 tasks from Azure DevOps:
  
  **AZ-123** - Implement user profile API endpoints (Backend, 4h)
  **AZ-124** - Build user profile editing component (Frontend, 3h) 
  **AZ-125** - Add profile picture upload functionality (Backend, 2h)
  **AZ-126** - Create profile management test suite (Testing, 3h)
  
  **Feature:** User Profile Management
  **Total Effort:** ~12 hours
  **Dependencies:** AZ-124 depends on AZ-123, AZ-126 tests all functionality
  
  📝 **ENHANCEMENT PREVIEW**
  
  If you proceed, I will:
  ✅ Analyze these tasks for user story grouping
  ✅ Group by business domain (User Management)
  ✅ Create implementation groups based on technical stack
  ✅ Enhance tasks to junior engineer readiness standards
  ✅ Generate comprehensive UAC and test cases
  ✅ Prepare coordinated implementation workflow
  
  **Do you want me to proceed with enhancement and workflow setup?**
  
  Options:
  1. **Yes, proceed** - Continue with enhancement and full workflow
  2. **No, continue without enhancing** - Continue with tasks as-is, skip enhancement
  3. **No, cancel** - Stop here and exit workflow
  4. **Show more details** - Display full task descriptions and analysis
  5. **Modify selection** - Remove or change selected tasks

### Batch Processing Results (After User Confirmation)
```yaml
batch_results:
  summary:
    total_tasks: 4
    successful_imports: 4
    failed_imports: 0
    user_confirmed: true
    confirmation_time: "2024-12-14T15:35:00Z"
    groups_created: 3
    coordination_agents_required: 3
  
  workflow_state:
    document_path: "workflow-state-{timestamp}.yaml"
    progress_checklist: "progress-checklist-{timestamp}.md"
    next_phase: "task_enhancement"
    coordination_ready: true
```

### Coordination Handoff Data
```yaml
handoff_package:
  target_agent: "hubtel-task-processor"
  workflow_context:
    - batch_import_complete: true
    - groups_analyzed: true
    - dependencies_mapped: true
    - enhancement_ready: true
  
  task_enhancement_queue:
    - group: "backend-api-group"
      tasks: ["AZ-123", "AZ-125"]
      context: "API development with Entity Framework"
    - group: "frontend-ui-group"
      tasks: ["AZ-124"]
      context: "Next.js component with API integration"
    - group: "testing-validation-group"
      tasks: ["AZ-126"] 
      context: "Comprehensive testing suite with coverage requirements"
  
  progress_tracking:
    workflow_state_file: "workflow-state-{timestamp}.yaml"
    live_checklist: "progress-checklist-{timestamp}.md"
    coordination_protocol: "automatic"
```

## Error Handling & Recovery

### Critical Failure Conditions (STOP Processing)
- **Any task retrieval failure**: If ANY requested task cannot be retrieved, STOP entire workflow
- **API connectivity failures**: If Hubtel API is unreachable, STOP and return connectivity error
- **HTTP error responses**: If API returns non-200 status, STOP and return HTTP error details
- **Invalid response format**: If API returns malformed JSON, STOP and return parsing error
- **Missing task data**: If response doesn't contain all requested tasks, STOP and list missing tasks

### Error Response Format
```yaml
error_response:
  status: "failed"
  error_type: "task_retrieval_failure" | "api_connectivity_error" | "http_error" | "invalid_response" | "missing_tasks"
  message: "Clear description of what went wrong"
  api_endpoint: "https://code-confidence-index.hubtel.com/api/azure-tasks"
  requested_tasks: ["260076", "260074", "260075", "260073"]
  retrieved_tasks: ["260076", "260074"]  # Only tasks successfully retrieved
  failed_tasks: ["260075", "260073"]     # Tasks that could not be retrieved
  curl_command_used: "curl --location 'https://code-confidence-index.hubtel.com/api/azure-tasks?ids=260076%2C260074%2C260075%2C260073'"
  http_status: 200 | 404 | 500 | null  # HTTP response status
  error_details:
    - task_id: "260075"
      error: "Task not found in Hubtel system"
    - task_id: "260073" 
      error: "Task not found in Hubtel system"
  resolution_steps:
    - "Verify task IDs exist in Azure DevOps"
    - "Check if tasks are accessible via Hubtel API"
    - "Ensure Hubtel API service is running"
    - "Verify network connectivity to code-confidence-index.hubtel.com"
  next_steps: "Verify task IDs and retry with valid task numbers"
```

### No Partial Processing
- **All or nothing approach**: Either retrieve ALL requested tasks or fail completely
- **No enhancement of partial data**: Do not proceed to task enhancement if any tasks are missing
- **Clear user feedback**: Provide specific information about which tasks failed and why
- **Actionable guidance**: Give user clear steps to resolve the issues

### Retry Guidance
- **Fix access issues first**: User must resolve permissions before retrying
- **Verify task IDs**: Ensure all task IDs are correct and exist
- **Re-run with corrected parameters**: Retry the same command after fixes

## Integration Points

### Agent Coordination
- **Next agent**: `hubtel-task-processor` for bulk enhancement
- **Coordination data**: Full handoff package with workflow context
- **Progress tracking**: Continuous updates to workflow state and checklist

### Workflow Integration
- **Isaac orchestrator**: Reports completion and next phase requirements
- **Progress visibility**: Real-time updates via progress checklist
- **Error reporting**: Detailed error context for workflow recovery

### Quality Standards
- **Batch size limits**: Maximum 20 tasks per batch for optimal performance
- **Data validation**: Ensure all required fields present before grouping
- **Coordination validation**: Verify all handoff data complete before agent transition