@cloudkinetix/bmad-enhanced/expansion-packs/ck-jira-integration/utils/reasoning-engine.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

---
name: JIRA Multi-turn Reasoning Engine
version: 1.0.0
role: Coordinate complex multi-step operations with intelligent decision making
description: Manages conversational flows, decision trees, and complex reasoning for JIRA operations
capabilities:
  - Multi-turn conversation management
  - Intelligent decision routing
  - Context-aware guidance
  - Progressive disclosure
  - Checkpoint and recovery
---

# JIRA Multi-turn Reasoning Engine

You orchestrate intelligent multi-turn interactions, breaking down complex requests into manageable conversations with clear decision points and user guidance.

## Core Architecture

### 1. Reasoning Session Manager

```javascript
class ReasoningSession {
  constructor(sessionId, initialRequest) {
    this.sessionId = sessionId;
    this.request = initialRequest;
    this.state = {
      phase: "analysis",
      turns: [],
      decisions: [],
      context: {},
      checkpoints: [],
    };
    this.intents = this.analyzeIntents(initialRequest);
  }

  // Analyze user request complexity
  analyzeIntents(request) {
    return {
      primary: detectPrimaryIntent(request),
      complexity: assessComplexity(request),
      entities: extractEntities(request),
      constraints: identifyConstraints(request),
      ambiguities: findAmbiguities(request),
    };
  }

  // Generate next turn
  async generateNextTurn() {
    const currentPhase = this.state.phase;
    const phaseHandler = this.phaseHandlers[currentPhase];

    const turn = await phaseHandler.execute(this.state);

    this.state.turns.push(turn);
    this.updateCheckpoint();

    return turn;
  }

  // Process user response
  async processUserResponse(response) {
    const turn = this.state.turns[this.state.turns.length - 1];

    // Validate response
    const validation = await this.validateResponse(response, turn);
    if (!validation.valid) {
      return this.clarifyResponse(validation.issues);
    }

    // Extract decision
    const decision = this.extractDecision(response, turn);
    this.state.decisions.push(decision);

    // Update state
    this.updateState(decision);

    // Determine next phase
    this.state.phase = this.determineNextPhase();

    return this.generateNextTurn();
  }
}
```

### 2. Phase Management

```javascript
const phaseHandlers = {
  // Initial analysis phase
  analysis: {
    execute: async (state) => {
      const analysis = await analyzeRequest(state);

      return {
        type: "analysis_presentation",
        content: {
          message: formatAnalysis(analysis),
          options: generateInitialOptions(analysis),
          context_summary: analysis.summary,
        },
        expects: "confirmation_or_modification",
        can_skip: false,
      };
    },
  },

  // Gathering requirements
  requirements: {
    execute: async (state) => {
      const missing = identifyMissingInfo(state);

      if (missing.length === 0) {
        state.phase = "planning";
        return phaseHandlers.planning.execute(state);
      }

      return {
        type: "information_request",
        content: {
          message: `I need some additional information:`,
          questions: missing.map((m) => ({
            id: m.id,
            question: m.question,
            type: m.inputType,
            required: m.required,
            default: m.suggestedDefault,
          })),
        },
        expects: "structured_answers",
        can_skip: missing.every((m) => !m.required),
      };
    },
  },

  // Planning phase
  planning: {
    execute: async (state) => {
      const plan = await generateExecutionPlan(state);

      return {
        type: "plan_presentation",
        content: {
          message: "Here's my plan:",
          steps: plan.steps.map((s) => ({
            description: s.description,
            impact: s.impact,
            risk: s.riskLevel,
          })),
          estimated_time: plan.estimatedDuration,
          warnings: plan.warnings,
        },
        expects: "approval_or_modification",
        can_skip: false,
      };
    },
  },

  // Execution phase
  execution: {
    execute: async (state) => {
      const nextStep = getNextExecutionStep(state);

      if (!nextStep) {
        state.phase = "completion";
        return phaseHandlers.completion.execute(state);
      }

      if (nextStep.requiresConfirmation) {
        return {
          type: "execution_confirmation",
          content: {
            message: `Ready to ${nextStep.description}`,
            details: nextStep.details,
            reversible: nextStep.canRollback,
          },
          expects: "proceed_or_abort",
          can_skip: false,
        };
      }

      // Execute and report
      const result = await executeStep(nextStep);

      return {
        type: "execution_progress",
        content: {
          message: `Completed: ${nextStep.description}`,
          result: result.summary,
          next: describeNextStep(state),
        },
        expects: "continue_or_pause",
        can_skip: true,
      };
    },
  },

  // Completion phase
  completion: {
    execute: async (state) => {
      const summary = generateSummary(state);

      return {
        type: "operation_complete",
        content: {
          message: "Operation completed successfully!",
          summary: summary,
          next_actions: suggestNextActions(state),
        },
        expects: "feedback_or_done",
        can_skip: true,
      };
    },
  },
};
```

## Conversation Patterns

### 1. Epic Breakdown Conversation

```javascript
const epicBreakdownFlow = {
  id: "epic_breakdown_conversation",

  turns: [
    {
      id: "analyze_epic",
      engine: async (context) => {
        const epic = await fetchEpic(context.epicKey);
        const analysis = await analyzeEpicComplexity(epic);

        return {
          message: `I've analyzed epic ${epic.key}: "${epic.summary}"
          
          Here's what I found:
          - Scope: ${analysis.scopeSize} (${analysis.storyCountEstimate} potential stories)
          - Technical areas: ${analysis.technicalAreas.join(", ")}
          - Dependencies: ${analysis.dependencyCount} external dependencies
          - Risk level: ${analysis.riskLevel}
          
          How would you like to break this down?`,

          options: [
            {
              label: "By technical component",
              value: "component_based",
              description: "Frontend, Backend, Database, etc.",
            },
            {
              label: "By user journey",
              value: "journey_based",
              description: "User flows end-to-end",
            },
            {
              label: "By sprint capacity",
              value: "sprint_based",
              description: "Sized for your sprint velocity",
            },
            {
              label: "Let me customize",
              value: "custom",
            },
          ],
        };
      },
    },

    {
      id: "breakdown_approach",
      engine: async (context, userChoice) => {
        if (userChoice === "custom") {
          return {
            message: "Let's customize the breakdown. Please specify:",
            questions: [
              {
                id: "target_story_size",
                question: "Preferred story size (points)?",
                type: "select",
                options: ["3", "5", "8", "13"],
                default: "5",
              },
              {
                id: "include_tech_tasks",
                question: "Include technical tasks?",
                type: "boolean",
                default: true,
              },
              {
                id: "frontend_backend_split",
                question: "Split frontend/backend?",
                type: "boolean",
                default: false,
              },
            ],
          };
        }

        // Generate stories based on approach
        const stories = await generateStories(context, userChoice);

        return {
          message: `Based on ${userChoice} approach, I've generated ${stories.length} stories:`,
          content: formatStoryList(stories),
          actions: [
            "Review each story",
            "Adjust story points",
            "Add/remove stories",
            "Proceed with creation",
          ],
        };
      },
    },

    {
      id: "story_refinement",
      engine: async (context, action) => {
        if (action === "Review each story") {
          return startStoryReviewFlow(context);
        }
        // Handle other actions...
      },
    },
  ],
};
```

### 2. Sprint Planning Conversation

```javascript
const sprintPlanningFlow = {
  id: "sprint_planning_conversation",

  turns: [
    {
      id: "capacity_check",
      engine: async (context) => {
        const capacity = await calculateTeamCapacity(context);
        const velocity = await getHistoricalVelocity(context);

        return {
          message: `Let's plan your sprint. Here's what I know:
          
          Team Capacity: ${capacity.available} hours (${capacity.storyPoints} points)
          Historical Velocity: ${velocity.average} ± ${velocity.stdDev} points
          Current Sprint: ${context.sprintName}
          
          What's your planning goal for this sprint?`,

          options: [
            {
              label: "Fill to velocity",
              value: "velocity_based",
              hint: `Target ~${velocity.average} points`,
            },
            {
              label: "Focus on specific epic",
              value: "epic_focused",
            },
            {
              label: "Clear tech debt",
              value: "tech_debt",
            },
            {
              label: "Mixed approach",
              value: "balanced",
            },
          ],
        };
      },
    },
  ],
};
```

## Decision Support

### 1. Intelligent Recommendations

```javascript
class RecommendationEngine {
  generateRecommendations(context, decision_point) {
    const recommendations = [];

    // Analyze context
    const patterns = analyzeHistoricalPatterns(context);
    const constraints = identifyConstraints(context);
    const risks = assessRisks(context);

    // Generate recommendations
    if (decision_point === "story_sizing") {
      recommendations.push({
        recommendation: "Use 5-point stories",
        reasoning: "Your team completes 5-point stories 15% faster",
        confidence: 0.85,
        based_on: "Last 10 sprints analysis",
      });
    }

    if (decision_point === "sprint_capacity") {
      recommendations.push({
        recommendation: `Plan for ${patterns.optimal_capacity} points`,
        reasoning: "Accounts for typical meetings and interruptions",
        confidence: 0.9,
        based_on: "Team's sustainable pace",
      });
    }

    return {
      primary: recommendations[0],
      alternatives: recommendations.slice(1),
      factors_considered: [patterns, constraints, risks],
    };
  }
}
```

### 2. Risk Assessment

```javascript
function assessOperationRisk(operation, context) {
  const riskFactors = {
    complexity: calculateComplexity(operation),
    dependencies: analyzeDependencies(operation),
    team_availability: checkTeamAvailability(context),
    timeline_pressure: assessTimelinePressure(context),
    technical_uncertainty: evaluateTechnicalRisk(operation),
  };

  const overallRisk = calculateOverallRisk(riskFactors);

  return {
    level: overallRisk.level, // 'low', 'medium', 'high'
    score: overallRisk.score, // 0-100
    factors: riskFactors,
    mitigations: generateMitigations(riskFactors),
    recommendation:
      overallRisk.level === "high"
        ? "Consider breaking into smaller operations"
        : "Proceed with standard precautions",
  };
}
```

## State Management

### 1. Conversation State

```javascript
class ConversationState {
  constructor() {
    this.state = {
      // Current conversation
      turn_count: 0,
      current_topic: null,
      pending_questions: [],
      answered_questions: [],

      // User preferences learned
      preferences: {
        detail_level: "medium", // low, medium, high
        confirmation_style: "explicit", // explicit, implicit
        pace: "measured", // fast, measured, careful
      },

      // Operation state
      operation: {
        type: null,
        progress: 0,
        completed_steps: [],
        pending_steps: [],
        decisions_made: [],
      },

      // Context accumulation
      context: {
        entities: new Map(),
        constraints: [],
        preferences: [],
        history: [],
      },
    };
  }

  updateFromTurn(turn, response) {
    this.state.turn_count++;
    this.state.answered_questions.push({
      question: turn.content,
      answer: response,
      timestamp: new Date(),
    });

    // Learn from interaction
    this.learnUserPreferences(turn, response);

    // Update operation progress
    this.updateOperationProgress(turn);
  }

  learnUserPreferences(turn, response) {
    // Adjust detail level based on follow-up questions
    if (response.includes("more detail")) {
      this.state.preferences.detail_level = "high";
    }

    // Adjust pace based on response time
    const responseTime = turn.response_time;
    if (responseTime < 5000) {
      this.state.preferences.pace = "fast";
    }
  }
}
```

### 2. Checkpoint Management

```javascript
class CheckpointManager {
  createCheckpoint(session) {
    return {
      id: generateCheckpointId(),
      session_id: session.sessionId,
      timestamp: new Date(),
      state: deepClone(session.state),
      resumable: true,
      expires: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
    };
  }

  canResume(checkpoint) {
    return (
      checkpoint.resumable &&
      checkpoint.expires > new Date() &&
      this.validateCheckpoint(checkpoint)
    );
  }

  resume(checkpoint) {
    const session = new ReasoningSession(
      checkpoint.session_id,
      checkpoint.state.request,
    );

    session.state = checkpoint.state;

    // Generate resume message
    const resumeMessage = this.generateResumeMessage(checkpoint);

    return {
      session,
      message: resumeMessage,
    };
  }

  generateResumeMessage(checkpoint) {
    const timeSince = Date.now() - checkpoint.timestamp;
    const lastAction = checkpoint.state.operation.completed_steps.slice(-1)[0];

    return `Welcome back! We were ${checkpoint.state.operation.type} and last completed: ${lastAction}. 
            Shall we continue from where we left off?`;
  }
}
```

## User Guidance

### 1. Progressive Disclosure

```javascript
class ProgressiveDisclosure {
  generateResponse(content, userPreferences) {
    const detailLevel = userPreferences.detail_level || "medium";

    const response = {
      summary: this.generateSummary(content),
      details: detailLevel !== "low" ? this.generateDetails(content) : null,
      advanced: detailLevel === "high" ? this.generateAdvanced(content) : null,
      actions: this.generateActions(content, detailLevel),
    };

    return this.formatResponse(response, detailLevel);
  }

  formatResponse(response, detailLevel) {
    if (detailLevel === "low") {
      return `${response.summary}\n\n${this.formatActions(response.actions)}`;
    }

    if (detailLevel === "medium") {
      return `${response.summary}\n\n${response.details}\n\n${this.formatActions(response.actions)}`;
    }

    return `${response.summary}\n\n${response.details}\n\n📊 Advanced Details:\n${response.advanced}\n\n${this.formatActions(response.actions)}`;
  }
}
```

### 2. Contextual Help

```javascript
class ContextualHelp {
  provideHelp(context, confusion_indicator) {
    const helpTopics = this.identifyHelpNeeds(context, confusion_indicator);

    return {
      immediate_help: this.generateImmediateHelp(helpTopics[0]),
      related_topics: helpTopics.slice(1, 4),
      examples: this.findRelevantExamples(context),
      common_issues: this.getCommonIssues(context.operation.type),
    };
  }

  detectConfusion(response, expected_type) {
    const indicators = [
      response.includes("?"),
      response.length < 10,
      response.toLowerCase().includes("not sure"),
      response.toLowerCase().includes("help"),
      !matchesExpectedType(response, expected_type),
    ];

    return indicators.filter((i) => i).length >= 2;
  }
}
```

## Integration Examples

### With Context Manager

```markdown
The reasoning engine uses context to:

- Remember previous decisions
- Apply learned preferences
- Skip redundant questions
- Provide relevant suggestions
```

### With Prompt Chains

```markdown
Reasoning engine orchestrates chains by:

- Breaking complex ops into conversations
- Collecting inputs for chain execution
- Presenting progress updates
- Handling chain interruptions gracefully
```

## Best Practices

1. **Clear Communication**: Always explain what you're doing and why
2. **User Control**: Let users skip, modify, or abort at any time
3. **Smart Defaults**: Use context to minimize questions
4. **Graceful Degradation**: Handle interruptions smoothly
5. **Learn and Adapt**: Improve based on user interactions

Remember: The goal is to make complex operations feel like natural conversations.