gateway/WORKFLOW_IMPLEMENTATION_GAPS.md

Workflow Implementation Gaps Analysis

Overview

After refactoring the AI process for fast track and full track, the workflow implementation does not match the architecture described in ai_plan_architecture.md. This document identifies the gaps and missing implementations.

---

Critical Issues Found

1. ❌ Fast Path Implementation Missing

Architecture Requirement (ai_plan_architecture.md lines 377-395):

• detectComplexity() function to determine "simple" | "moderate" | "complex"
• fastPathExecute() function for simple requests (5-15s)
• Fast path should skip full workflow and return directly

Current Implementation:

• ❌ NO detectComplexity() function found
• ❌ NO fastPathExecute() function found
• ❌ NO complexity detection before workflow execution
• ✅ User intention analysis exists but doesn't route to fast path

Location: Should be in workflowManager.py before _planTasks()

Impact: All requests go through full workflow, even simple ones that could be answered in 5-15s.

---

2. ❌ Task Numbering Always Shows "Task 0"

Architecture Requirement (ai_plan_architecture.md lines 117-152):

• ChatWorkflow.currentTask should increment properly
• workflow.incrementTask() should be called when starting new task
• Task numbers should be 1-indexed for display

Current Implementation:

• ✅ ChatWorkflow.currentTask field exists
• ✅ _updateWorkflowBeforeExecutingTask() exists in modeDynamic.py (line 902)
• ❌ NOT CALLED from workflowManager._executeTasks() (line 368)
• ❌ Task index calculation uses idx + 1 but never updates workflow.currentTask
• ❌ Messages show taskNumber: 0 because currentTask is never incremented

Problem Location: workflowManager.py line 368-396

Current Code:

for idx, taskStep in enumerate(taskPlan.tasks):
    currentTaskIndex = idx + 1  # Calculated but never used to update workflow
    logger.info(f"Task {currentTaskIndex}/{totalTasks}: {taskStep.objective}")
    # ... task execution ...
    taskResult = await handling.executeTask(taskStep, workflow, taskContext)
    # ❌ Missing: workflow.currentTask = currentTaskIndex
    # ❌ Missing: workflow.incrementTask() or updateWorkflowBeforeExecutingTask()

Fix Required:

for idx, taskStep in enumerate(taskPlan.tasks):
    currentTaskIndex = idx + 1
    logger.info(f"Task {currentTaskIndex}/{totalTasks}: {taskStep.objective}")
    
    # ✅ ADD: Update workflow before executing task
    handling.updateWorkflowBeforeExecutingTask(currentTaskIndex)
    
    # ... task execution ...
    taskResult = await handling.executeTask(taskStep, workflow, taskContext)

Impact: UI always shows "Task 0" instead of "Task 1", "Task 2", etc.

---

3. ❌ User Language Not in ChatMessages

Architecture Requirement (ai_plan_architecture.md lines 1300-1321):

• ChatMessages should contain user-friendly text in user's language
• User-facing workflows: Full ChatMessage with user language
• Process automation: Minimal ChatMessage (system role)

Current Implementation:

• ✅ User language detection exists (workflowManager.py line 256-277)
• ✅ userMessage field exists in TaskStep and TaskPlan
• ❌ Messages use technical text instead of user-friendly language
• ❌ No AI-generated user messages in user's language
• ❌ Messages show action names (ai.process, outlook.readMails) instead of user-friendly descriptions

Problem Locations:

1. messageCreator.py line 136-145: Uses action.userMessage if available, but this is often missing
2. messageCreator.py line 77: Task start message is just "🚀 **Task {taskProgress}**" - no user-friendly text
3. messageCreator.py line 204: Task completion message is generic "✅ Task completed successfully" - not in user language

Example Current Message:

🚀 **Task 1**

💬 Analyze the provided documents and extract key information

Should Be (in user's language, e.g., German):

🚀 **Aufgabe 1**

💬 Ich analysiere die bereitgestellten Dokumente und extrahiere die wichtigsten Informationen für Sie.

Fix Required:

1. Generate user-friendly messages in user's language during task planning
2. Store user messages in TaskStep.userMessage (already exists but not populated)
3. Use user messages in messageCreator.py instead of technical action names

Impact: Users see technical messages instead of friendly, localized messages.

---

4. ❌ Workflow-Level Architecture Not Implemented

Architecture Requirement (ai_plan_architecture.md lines 368-428):

• RequestContext model for normalized request
• UnderstandingResult model for initial understanding
• TaskDefinition model with extractionOptions
• TaskResult model for task results
• persistTaskResult() function to create ChatMessages

Current Implementation:

• ❌ NO RequestContext model
• ❌ NO UnderstandingResult model
• ❌ NO TaskDefinition model (using TaskStep instead)
• ❌ NO TaskResult model (using ActionResult instead)
• ❌ NO persistTaskResult() function
• ✅ TaskStep exists but doesn't match TaskDefinition structure

Impact: Workflow-level architecture described in ai_plan_architecture.md is not implemented. The system uses old TaskStep model instead of new TaskDefinition model.

---

5. ❌ Initial Understanding Phase Missing

Architecture Requirement (ai_plan_architecture.md lines 411-414):

• initialUnderstanding(context) → UnderstandingResult
• Combined AI call: parameters + intention + context + tasks
• Creates TaskDefinition[] from UnderstandingResult

Current Implementation:

• ✅ User intention analysis exists (workflowManager.py line 221-289)
• ❌ NOT structured as initialUnderstanding() function
• ❌ NOT returning UnderstandingResult model
• ❌ NOT creating TaskDefinition[] - creates TaskStep[] instead
• ❌ NO combined AI call - separate calls for different purposes

Impact: Initial understanding phase doesn't match architecture. Uses old approach instead of new unified UnderstandingResult model.

---

Summary of Missing Implementations

Component	Status	Priority	Location
Fast Path (fastPathExecute)	❌ Missing	🔴 Critical	workflowManager.py
Complexity Detection (detectComplexity)	❌ Missing	🔴 Critical	workflowManager.py
Task Numbering Update	❌ Not Called	🔴 Critical	workflowManager._executeTasks()
User Language Messages	⚠️ Partial	🟡 High	messageCreator.py
RequestContext Model	❌ Missing	🟡 High	datamodelWorkflow.py
UnderstandingResult Model	❌ Missing	🟡 High	datamodelWorkflow.py
TaskDefinition Model	❌ Missing	🟡 High	datamodelWorkflow.py
TaskResult Model	❌ Missing	🟡 High	datamodelWorkflow.py
persistTaskResult()	❌ Missing	🟡 High	workflowProcessor.py
initialUnderstanding()	❌ Missing	🟡 High	workflowProcessor.py

---

Recommended Fix Order

Phase 1: Critical Fixes (Immediate)

1. Fix Task Numbering (30 min)

   • Call updateWorkflowBeforeExecutingTask() in workflowManager._executeTasks()
   • Verify currentTask increments properly

2. Add Fast Path Detection (2 hours)

   • Implement detectComplexity() function
   • Add routing logic to fastPathExecute() for simple requests
   • Test with simple vs. complex prompts

Phase 2: User Experience (High Priority)

3. Generate User-Friendly Messages (4 hours)
   • Add AI call to generate user messages in user's language
   • Update messageCreator.py to use user messages
   • Test with different languages

Phase 3: Architecture Alignment (Medium Priority)

4. Implement Workflow-Level Models (8 hours)

   • Create RequestContext, UnderstandingResult, TaskDefinition, TaskResult models
   • Migrate from TaskStep to TaskDefinition
   • Update all call sites

5. Implement Initial Understanding (4 hours)

   • Create initialUnderstanding() function
   • Return UnderstandingResult model
   • Create TaskDefinition[] from result

---

Code References

Current Task Execution Flow

• Entry Point: workflowManager.py line 166 → _executeTasks()
• Task Loop: workflowManager.py line 368-396
• Task Execution: workflowProcessor.py → executeTask()
• Message Creation: messageCreator.py → createTaskStartMessage(), createActionMessage()

Missing Fast Path Flow

• Should Be: workflowManager.py → detectComplexity() → fastPathExecute() OR _planTasks()
• Currently: Always goes to _planTasks() → _executeTasks()

Task Numbering Issue

• Problem: workflowManager._executeTasks() line 369 calculates currentTaskIndex but never updates workflow.currentTask
• Solution: Call handling.updateWorkflowBeforeExecutingTask(currentTaskIndex) before executeTask()

---

Testing Checklist

After fixes, verify:

• Simple requests use fast path (5-15s response time)
• Complex requests use full workflow (30-120s response time)
• Task numbers increment correctly (Task 1, Task 2, Task 3...)
• ChatMessages contain user-friendly text in user's language
• User messages are generated, not technical action names
• Workflow state (currentTask, currentRound, currentAction) updates correctly

---

Next Steps

1. Immediate: Fix task numbering (30 min fix, high impact)
2. This Week: Implement fast path detection and routing
3. Next Sprint: Add user-friendly message generation
4. Future: Migrate to workflow-level models (TaskDefinition, UnderstandingResult, etc.)