# 🤖 AI-Powered Workflow Orchestration Guide

This guide covers the advanced AI-powered features of the MCP ADR Analysis Server, including intelligent tool orchestration, human override capabilities, and systematic troubleshooting workflows.

## 🧠 Overview of AI-Powered Features

The MCP ADR Analysis Server includes several AI-powered tools that leverage OpenRouter.ai and advanced prompt engineering to provide intelligent workflow automation:

### Core AI Tools

- **Tool Chain Orchestrator** - Dynamic tool sequencing based on user intent
- **Troubleshooting Workflow** - Systematic failure analysis with test plan generation
- **Smart Project Scoring** - Cross-tool health assessment with AI optimization

### Key Benefits

- **Hallucination Prevention** - Reality checks and structured planning prevent AI confusion
- **Dynamic Workflow Generation** - AI analyzes context to generate optimal tool sequences
- **Intelligent Fallbacks** - Template-based approaches when AI services are unavailable
- **Cross-Tool Coordination** - Tools work together for comprehensive project insights

## 🔗 Tool Chain Orchestrator

The Tool Chain Orchestrator is the central AI-powered planning system that generates intelligent tool execution sequences.

### Core Operations

#### Generate Execution Plan

```json
{
  "operation": "generate_plan",
  "userRequest": "Complete architectural analysis and generate implementation roadmap",
  "includeContext": true,
  "optimizeFor": "comprehensive"
}
```

**What it does:**

- Analyzes user intent using OpenRouter.ai
- Generates structured tool execution sequences
- Provides dependency analysis and execution order
- Includes confidence scoring and alternative approaches

#### Analyze User Intent

```json
{
  "operation": "analyze_intent",
  "userRequest": "Help me understand why my deployment is failing",
  "extractGoals": true
}
```

**Use Cases:**

- Understanding complex user requests
- Goal extraction from natural language
- Intent classification for workflow selection

#### Suggest Relevant Tools

```json
{
  "operation": "suggest_tools",
  "userRequest": "I need to improve my project's architectural documentation",
  "maxSuggestions": 5
}
```

### Common Workflow Patterns

When LLMs get confused or for systematic workflows, use these proven tool sequences:

#### Complete Project Analysis

**Tools:** `analyze_project_ecosystem` → `discover_existing_adrs` → `suggest_adrs` → `smart_score`

#### Generate Documentation

**Tools:** `generate_adr_todo` → `generate_deployment_guidance` → `generate_rules`

#### Security Audit and Fix

**Tools:** `analyze_content_security` → `suggest_adrs` → `generate_rules` → `validate_rules`

#### Deployment Readiness

**Tools:** `compare_adr_progress` → `smart_score` → `generate_deployment_guidance` → `smart_git_push`

#### Systematic Troubleshooting

**Tools:** `troubleshoot_guided_workflow` → `smart_score` → `compare_adr_progress`

#### Complete TODO Management

**Tools:** `generate_adr_todo` → `manage_todo` → `compare_adr_progress` → `smart_score`

### Advanced Features

#### Reality Check for Hallucination Detection

```json
{
  "operation": "reality_check",
  "sessionContext": "Previous conversation context",
  "detectConfusion": true
}
```

**Hallucination Indicators:**

- Repetitive tool suggestions
- Circular reasoning patterns
- Requests for non-existent tools
- Inconsistent parameter suggestions

#### Session Guidance for Long Conversations

```json
{
  "operation": "session_guidance",
  "conversationLength": "long",
  "provideSummary": true
}
```

**Provides:**

- Conversation summary and progress
- Suggested next steps
- Warning about potential confusion
- Reset recommendations

## 🚨 Human Override System

The Human Override system forces AI-powered planning when LLMs get confused or stuck in loops.

### When to Use Human Override

**Indicators you need human override:**

- LLM asking repetitive questions
- Circular conversation patterns
- LLM claiming tools don't exist
- Inconsistent or contradictory suggestions
- LLM seems "stuck" or confused

### Core Operations

#### Force AI Planning

```json
{
  "taskDescription": "Set up complete ADR infrastructure with deployment pipeline",
  "forceExecution": true,
  "includeContext": true
}
```

**What it does:**

- Bypasses current LLM confusion
- Forces fresh AI analysis through OpenRouter.ai
- Generates structured execution plans
- Provides clear command schemas for LLM consumption

#### Extract Goals from Natural Language

```json
{
  "taskDescription": "The build is broken and tests are failing, need to fix everything",
  "forceExecution": true,
  "extractGoals": true
}
```

**Goal Extraction Example:**

- Input: "The build is broken and tests are failing, need to fix everything"
- Extracted Goals: ["Fix build issues", "Resolve test failures", "Validate system stability"]

### Integration with Knowledge Graph

The Human Override system integrates with the Knowledge Graph to:

- Track human intervention patterns
- Record forced execution contexts
- Analyze effectiveness of override strategies
- Provide analytics on LLM confusion patterns

## 🔧 Troubleshooting Guided Workflow

Systematic problem-solving with ADR/TODO alignment and AI-powered test plan generation.

### Supported Failure Types

- **test_failure** - Unit/integration test failures
- **deployment_failure** - Production deployment issues
- **build_failure** - Compilation or build process failures
- **runtime_error** - Application runtime exceptions
- **performance_issue** - Performance degradation problems
- **security_issue** - Security vulnerabilities or breaches

### Core Operations

#### Analyze Failure

```json
{
  "operation": "analyze_failure",
  "failureType": "deployment_failure",
  "description": "Kubernetes deployment failing with connection timeouts",
  "severity": "high",
  "context": {
    "environment": "production",
    "lastWorkingVersion": "v2.1.0",
    "errorDetails": "Connection timeout after 30s"
  }
}
```

#### Generate AI-Powered Test Plan

```json
{
  "operation": "generate_test_plan",
  "failureType": "build_failure",
  "description": "TypeScript compilation failing after dependency update",
  "severity": "medium"
}
```

**AI-Generated Output:**

```json
{
  "testPlan": {
    "diagnosticCommands": [
      "npx tsc --noEmit --listFiles",
      "npm ls typescript",
      "npx tsc --showConfig"
    ],
    "validationSteps": [
      "Verify TypeScript version compatibility",
      "Check for conflicting type definitions",
      "Validate tsconfig.json configuration"
    ],
    "expectedOutcomes": [
      "TypeScript version should be compatible with dependencies",
      "No duplicate type definitions should exist",
      "Configuration should match project requirements"
    ]
  }
}
```

#### Full Workflow Integration

```json
{
  "operation": "full_workflow",
  "failureType": "security_issue",
  "description": "Potential sensitive data exposure in logs",
  "severity": "critical"
}
```

**Full Workflow Steps:**

1. Analyze failure with AI-powered assessment
2. Generate specific test plan with commands
3. Execute `analyze_content_security` for sensitive data detection
4. Run `suggest_adrs` for security-related architectural decisions
5. Use `generate_rules` to create security compliance rules
6. Execute `smart_score` to assess security posture improvement

## 📊 Smart Project Scoring System

Cross-tool coordination for comprehensive project health assessment.

### Core Operations

#### Recalculate All Scores

```json
{
  "operation": "recalculate_scores",
  "updateSources": true,
  "includeOptimization": true
}
```

#### Synchronize Cross-Tool Scores

```json
{
  "operation": "sync_scores",
  "rebalanceWeights": true,
  "focusAreas": ["todo", "architecture", "security", "deployment"]
}
```

#### Comprehensive Health Diagnostics

```json
{
  "operation": "diagnose_scores",
  "includeRecommendations": true,
  "dataFreshness": true
}
```

#### AI-Driven Weight Optimization

```json
{
  "operation": "optimize_weights",
  "projectType": "web-application",
  "optimizationGoal": "deployment_readiness"
}
```

### Score Components

**Default Scoring Weights:**

- TODO Completion: 30%
- Architecture Compliance: 25%
- Security Posture: 20%
- Deployment Readiness: 15%
- Code Quality: 10%

**Project-Specific Optimization:**

- **Startup Projects**: Higher weight on TODO completion and deployment readiness
- **Enterprise Applications**: Higher weight on security and architecture compliance
- **Open Source**: Higher weight on code quality and documentation

## 🔄 Best Practices for AI-Powered Workflows

### 1. Start with Tool Orchestration

For complex tasks, always begin with:

```json
{
  "operation": "generate_plan",
  "userRequest": "Your specific goal",
  "includeContext": true
}
```

### 2. Use Human Override When Stuck

If conversation becomes circular:

```json
{
  "taskDescription": "Clear description of what you want to achieve",
  "forceExecution": true
}
```

### 3. Leverage Troubleshooting for Problems

For any failure or issue:

```json
{
  "operation": "full_workflow",
  "failureType": "appropriate_type",
  "description": "Specific problem description"
}
```

### 4. Monitor Health Continuously

Regular health checks:

```json
{
  "operation": "diagnose_scores",
  "includeRecommendations": true
}
```

### 5. Validate with Reality Checks

Prevent AI confusion:

```json
{
  "operation": "reality_check",
  "detectConfusion": true
}
```

## 🚀 Advanced Integration Patterns

### Workflow Chaining

Combine AI-powered tools for comprehensive workflows:

1. **Initial Planning**: `tool_chain_orchestrator` generates plan
2. **Execution**: Follow generated tool sequence
3. **Validation**: `smart_score` assesses results
4. **Troubleshooting**: `troubleshoot_guided_workflow` if issues arise
5. **Restart**: Start fresh session if confusion occurs

### Context Preservation

Maintain context across tool executions:

- Include conversation history in orchestration requests
- Use knowledge graph to track intent progressions
- Leverage smart scoring for continuous assessment

### Fallback Strategies

Always have fallbacks when AI is unavailable:

- Predefined task patterns in orchestrator
- Template-based test plans in troubleshooting
- Manual workflow guides for common scenarios

## 🎯 Common Scenarios and Solutions

### Scenario 1: LLM Keeps Asking Same Questions

**Solution:** Use Human Override

```json
{
  "taskDescription": "Complete architectural analysis for microservices project",
  "forceExecution": true
}
```

### Scenario 2: Complex Multi-Step Task

**Solution:** Use Tool Orchestration

```json
{
  "operation": "generate_plan",
  "userRequest": "Migrate monolith to microservices with full documentation",
  "optimizeFor": "comprehensive"
}
```

### Scenario 3: Deployment Keeps Failing

**Solution:** Use Troubleshooting Workflow

```json
{
  "operation": "full_workflow",
  "failureType": "deployment_failure",
  "description": "Specific deployment error details"
}
```

### Scenario 4: Project Health Declining

**Solution:** Use Smart Scoring Diagnostics

```json
{
  "operation": "diagnose_scores",
  "includeRecommendations": true,
  "focusAreas": ["todo", "architecture", "deployment"]
}
```

## 🔮 Future Enhancements

### Planned AI Improvements

1. **Enhanced Hallucination Detection** - More sophisticated confusion pattern recognition
2. **Learning from Patterns** - AI learns from successful workflow patterns
3. **Cross-Project Insights** - Share knowledge across different projects
4. **Advanced Context Understanding** - Better long-term conversation context
5. **Predictive Troubleshooting** - Anticipate issues before they occur

### Integration Roadmap

- **CI/CD Integration** - Automated workflow orchestration in pipelines
- **IDE Extensions** - Real-time AI guidance during development
- **Team Collaboration** - Shared AI insights and workflow patterns
- **Advanced Analytics** - Project health prediction and optimization

---

**Need Help?**

- Check the main [README](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/README.md) for basic setup
- Review specific tool guides for detailed parameters
- Open an issue on [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server/issues) for AI-related problems
