Decision Frameworks

What this skill does

# Decision Frameworks Skill

## Overview

This skill provides decision-making frameworks, scoring methodologies, and planning strategies specifically for **Group 2 (Decision Making & Planning)** agents in the four-tier architecture. It covers how to evaluate Group 1 recommendations, incorporate user preferences, create execution plans, and make optimal decisions that balance multiple factors.

## When to Apply This Skill

**Use this skill when:**
- Evaluating recommendations from Group 1 (Strategic Analysis & Intelligence)
- Creating execution plans for Group 3 (Execution & Implementation)
- Prioritizing competing recommendations
- Incorporating user preferences into decisions
- Balancing trade-offs (speed vs quality, risk vs benefit)
- Deciding between multiple valid approaches
- Optimizing for specific objectives (quality, speed, cost)

**Required for:**
- strategic-planner (master decision-maker)
- preference-coordinator (user preference specialist)
- Any Group 2 agent making planning decisions

## Group 2 Role Recap

**Group 2: Decision Making & Planning (The "Council")**
- **Input**: Recommendations from Group 1 with confidence scores
- **Process**: Evaluate, prioritize, decide, plan
- **Output**: Execution plans for Group 3 with priorities and preferences
- **Key Responsibility**: Make optimal decisions balancing analysis, user preferences, historical success, and risk

## Decision-Making Frameworks

### Framework 1: Recommendation Evaluation Matrix

**Purpose**: Score each Group 1 recommendation on multiple dimensions

**Scoring Formula (0-100)**:
```python
Recommendation Score =
  (Confidence from Group 1    × 30%) +  # How confident is the analyst?
  (User Preference Alignment  × 25%) +  # Does it match user style?
  (Historical Success Rate    × 25%) +  # Has this worked before?
  (Risk Assessment            × 20%)    # What's the risk level?

Where each component is 0-100
```

**Implementation**:
```python
def evaluate_recommendation(recommendation, user_prefs, historical_data):
    # Component 1: Confidence from Group 1 (0-100)
    confidence_score = recommendation.get("confidence", 0.5) * 100

    # Component 2: User Preference Alignment (0-100)
    preference_score = calculate_preference_alignment(
        recommendation,
        user_prefs
    )

    # Component 3: Historical Success Rate (0-100)
    similar_patterns = query_similar_tasks(recommendation)
    if similar_patterns:
        success_rate = sum(p.success for p in similar_patterns) / len(similar_patterns)
        historical_score = success_rate * 100
    else:
        historical_score = 50  # No data → neutral

    # Component 4: Risk Assessment (0-100, higher = safer)
    risk_score = assess_risk(recommendation)

    # Weighted average
    total_score = (
        confidence_score * 0.30 +
        preference_score * 0.25 +
        historical_score * 0.25 +
        risk_score * 0.20
    )

    return {
        "total_score": total_score,
        "confidence_score": confidence_score,
        "preference_score": preference_score,
        "historical_score": historical_score,
        "risk_score": risk_score
    }
```

**Interpretation**:
- **85-100**: Excellent recommendation - high confidence to proceed
- **70-84**: Good recommendation - proceed with standard caution
- **50-69**: Moderate recommendation - proceed carefully or seek alternatives
- **0-49**: Weak recommendation - consider rejecting or modifying significantly

### Framework 2: Multi-Criteria Decision Analysis (MCDA)

**Purpose**: Choose between multiple competing recommendations

**Method**: Weighted scoring across criteria

**Example - Choosing Between 3 Refactoring Approaches**:
```python
criteria = {
    "quality_impact": 0.30,      # How much will quality improve?
    "effort_required": 0.25,     # How much time/work?
    "risk_level": 0.20,          # How risky is it?
    "user_alignment": 0.15,      # Matches user style?
    "maintainability": 0.10      # Long-term benefits?
}

options = [
    {
        "name": "Modular Refactoring",
        "quality_impact": 90,
        "effort_required": 60,  # Higher effort → lower score
        "risk_level": 80,  # Lower risk → higher score
        "user_alignment": 85,
        "maintainability": 95
    },
    {
        "name": "Incremental Refactoring",
        "quality_impact": 70,
        "effort_required": 85,  # Lower effort → higher score
        "risk_level": 90,
        "user_alignment": 90,
        "maintainability": 75
    },
    {
        "name": "Complete Rewrite",
        "quality_impact": 100,
        "effort_required": 20,  # Very high effort → very low score
        "risk_level": 40,  # High risk → low score
        "user_alignment": 60,
        "maintainability": 100
    }
]

def calculate_mcda_score(option, criteria):
    score = 0
    for criterion, weight in criteria.items():
        score += option[criterion] * weight
    return score

scores = {opt["name"]: calculate_mcda_score(opt, criteria) for opt in options}
# Result:
# Modular Refactoring: 82.5
# Incremental Refactoring: 81.0
# Complete Rewrite: 63.0
# → Choose Modular Refactoring
```

**Best Practices**:
- Adjust criterion weights based on user preferences
- Normalize all scores to 0-100 range
- Consider negative criteria (effort, risk) inversely
- Document rationale for weights used

### Framework 3: Risk-Benefit Analysis

**Purpose**: Evaluate decisions through risk-benefit lens

**Matrix**:
```
         Low Benefit    |    High Benefit
---------|---------------|------------------
Low Risk | ⚠️ Avoid      | ✅ Do It (Quick Win)
High Risk| ❌ Never Do   | 🤔 Careful Analysis Required
```

**Implementation**:
```python
def categorize_decision(benefit_score, risk_level):
    """
    benefit_score: 0-100 (higher = more benefit)
    risk_level: 0-100 (higher = more risky)
    """
    high_benefit = benefit_score >= 70
    low_risk = risk_level <= 30

    if high_benefit and low_risk:
        return "quick_win", "High benefit, low risk - proceed immediately"
    elif high_benefit and not low_risk:
        return "high_value_high_risk", "Requires careful analysis and mitigation strategies"
    elif not high_benefit and low_risk:
        return "avoid", "Not worth the effort even if safe"
    else:
        return "never_do", "High risk, low benefit - reject"
```

**Risk Factors to Consider**:
- **Technical Risk**: Breaking changes, backward compatibility, dependency issues
- **Schedule Risk**: Could delay other tasks, unknown complexity
- **Quality Risk**: Might introduce bugs, could reduce test coverage
- **User Impact**: Disrupts user workflow, changes behavior significantly
- **Reversibility**: Can we undo if it fails?

**Benefit Factors to Consider**:
- **Quality Impact**: Improves code quality, reduces technical debt
- **Performance Impact**: Makes system faster, more efficient
- **Maintainability Impact**: Easier to maintain and extend
- **User Experience Impact**: Better UX, fewer errors
- **Strategic Value**: Aligns with long-term goals

### Framework 4: Prioritization Matrix (Eisenhower Matrix)

**Purpose**: Prioritize multiple tasks by urgency and importance

**Matrix**:
```
           Not Urgent    |     Urgent
-----------|---------------|------------------
Important  | 📋 Schedule   | 🔥 Do First
Not Import | 🗑️ Eliminate  | ⚡ Delegate/Quick
```

**Implementation**:
```python
def prioritize_tasks(recommendations):
    prioritized = {
        "do_first": [],      # Urgent + Important
        "schedule": [],      # Not Urgent + Important
        "quick_wins": [],    # Urgent + Not Important
        "eliminate": []      # Not Urgent + Not Important
    }

    for rec in recommendations:
        urgent = (
            rec.get("priority") == "high" or
            rec.get("severity") in ["critical", "high"] or
            rec.get("user_impact") == "high"
        )

        important = (
            rec.get("expected_impact") == "high" or
            rec.get("quality_impact") >= 15 or