cqt-agent
Version:
415 lines (362 loc) • 17.4 kB
Markdown
# 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