decision-support

What this skill does

# decision-support

Facilitate data-driven technical decisions using embedded decision matrices and trade-off analysis.

## Triggers


Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "ADR" in decision context → Architecture Decision Record
- "ToT" / "tree of thought" → structured reasoning mode
- "pros and cons" → trade-off analysis

## Purpose

This skill facilitates structured decision-making for technical and architectural choices by:
- Building weighted decision matrices
- Analyzing trade-offs across multiple dimensions
- Documenting decision rationale
- Generating Architecture Decision Records (ADRs)
- Tracking decision outcomes

## Behavior

When triggered, this skill:

1. **Identifies decision context**:
   - Parse the decision question
   - Identify stakeholders and constraints
   - Determine decision type (architectural, technical, process)

2. **Gathers alternatives**:
   - List candidate options
   - Research each alternative
   - Document key characteristics

3. **Defines evaluation criteria**:
   - Identify relevant factors
   - Assign weights based on priorities
   - Define scoring rubrics

4. **Builds decision matrix**:
   - Score each option per criterion
   - Calculate weighted totals
   - Visualize comparisons

5. **Analyzes trade-offs**:
   - Identify strengths/weaknesses
   - Document risks per option
   - Consider long-term implications

6. **Generates recommendation**:
   - Provide data-backed recommendation
   - Document minority positions
   - Create ADR for record

## Decision Types

### Architectural Decisions

```yaml
architectural:
  examples:
    - database_selection
    - api_design_pattern
    - microservices_vs_monolith
    - authentication_approach
    - caching_strategy

  typical_criteria:
    - scalability
    - maintainability
    - performance
    - security
    - team_expertise
    - cost
    - time_to_implement
```

### Technical Decisions

```yaml
technical:
  examples:
    - library_selection
    - framework_choice
    - language_selection
    - testing_approach
    - ci_cd_tooling

  typical_criteria:
    - maturity
    - community_support
    - documentation
    - learning_curve
    - integration_ease
    - license_compatibility
```

### Process Decisions

```yaml
process:
  examples:
    - branching_strategy
    - release_cadence
    - review_process
    - documentation_approach
    - communication_tools

  typical_criteria:
    - team_fit
    - efficiency
    - quality_impact
    - adoption_effort
    - tooling_support
```

## Decision Matrix Template

```markdown
# Decision Matrix: [Decision Title]

**Decision ID**: DEC-2025-001
**Date**: 2025-12-08
**Status**: Under Evaluation
**Decision Owner**: [Name]
**Stakeholders**: [List]

## Context

[Description of the problem or opportunity requiring a decision]

## Constraints

- [Constraint 1]
- [Constraint 2]
- [Constraint 3]

## Options Under Consideration

### Option A: [Name]
- **Description**: [Brief description]
- **Pros**: [Key advantages]
- **Cons**: [Key disadvantages]
- **Risk Level**: Low/Medium/High

### Option B: [Name]
- **Description**: [Brief description]
- **Pros**: [Key advantages]
- **Cons**: [Key disadvantages]
- **Risk Level**: Low/Medium/High

### Option C: [Name]
- **Description**: [Brief description]
- **Pros**: [Key advantages]
- **Cons**: [Key disadvantages]
- **Risk Level**: Low/Medium/High

## Evaluation Criteria

| Criterion | Weight | Description |
|-----------|--------|-------------|
| Scalability | 25% | Ability to handle growth |
| Maintainability | 20% | Ease of ongoing maintenance |
| Performance | 20% | Speed and efficiency |
| Security | 15% | Security posture |
| Team Expertise | 10% | Team familiarity |
| Cost | 10% | Total cost of ownership |

## Scoring Rubric

| Score | Meaning |
|-------|---------|
| 5 | Excellent - Exceeds requirements |
| 4 | Good - Meets all requirements |
| 3 | Adequate - Meets most requirements |
| 2 | Poor - Meets some requirements |
| 1 | Unacceptable - Does not meet requirements |

## Decision Matrix

| Criterion | Weight | Option A | Option B | Option C |
|-----------|--------|----------|----------|----------|
| Scalability | 25% | 4 (1.00) | 5 (1.25) | 3 (0.75) |
| Maintainability | 20% | 5 (1.00) | 3 (0.60) | 4 (0.80) |
| Performance | 20% | 4 (0.80) | 5 (1.00) | 3 (0.60) |
| Security | 15% | 4 (0.60) | 4 (0.60) | 5 (0.75) |
| Team Expertise | 10% | 5 (0.50) | 2 (0.20) | 4 (0.40) |
| Cost | 10% | 3 (0.30) | 4 (0.40) | 3 (0.30) |
| **Total** | 100% | **4.20** | **4.05** | **3.60** |

## Trade-off Analysis

### Option A vs Option B
- **A wins on**: Maintainability (+2), Team Expertise (+3)
- **B wins on**: Scalability (+1), Performance (+1), Cost (+1)
- **Key trade-off**: Immediate productivity vs long-term scale

### Option A vs Option C
- **A wins on**: Scalability (+1), Maintainability (+1), Performance (+1)
- **C wins on**: Security (+1)
- **Key trade-off**: Overall capability vs security focus

## Risk Assessment

| Option | Key Risks | Mitigation |
|--------|-----------|------------|
| A | May hit scale limits in 2 years | Plan migration path |
| B | Learning curve may slow initial dev | Training budget |
| C | Performance concerns at scale | Performance testing |

## Recommendation

**Recommended Option**: Option A

**Rationale**:
1. Highest weighted score (4.20)
2. Strong team expertise reduces implementation risk
3. Best maintainability for long-term ownership
4. Acceptable scalability with documented migration path

**Dissenting Views**:
- [Stakeholder X] prefers Option B for scalability headroom
- Noted for future re-evaluation if growth exceeds projections

## Decision Record

**Decision**: Adopt Option A
**Decided By**: [Decision Owner]
**Date**: 2025-12-08
**Review Date**: 2026-06-08 (6 months)

## Action Items

- [ ] Document implementation approach
- [ ] Create ADR
- [ ] Communicate decision to team
- [ ] Set up review milestone
```

## ADR Generation

When a decision is finalized, generate an ADR:

```markdown
# ADR-XXX: [Decision Title]

## Status

Accepted

## Context

[Background and problem statement]

## Decision

We will use [Option A] because [rationale summary].

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

### Neutral
- [Observation 1]

## Alternatives Considered

### Option B: [Name]
Rejected because: [reason]

### Option C: [Name]
Rejected because: [reason]

## References

- Decision Matrix: .aiwg/decisions/DEC-2025-001.md
- Related ADRs: ADR-XXX
```

## Usage Examples

### Full Decision Analysis

```
User: "Help me decide between PostgreSQL and MongoDB for our user service"

Skill executes:
1. Identify decision: Database selection for user service
2. Gather alternatives: PostgreSQL, MongoDB, (suggests DynamoDB)
3. Define criteria based on user service requirements
4. Build comparison matrix
5. Analyze trade-offs
6. Generate recommendation

Output:
"Decision Analysis: User Service Database

Options Evaluated:
1. PostgreSQL (Score: 4.35)
2. MongoDB (Score: 3.90)
3. DynamoDB (Score: 3.65)

Recommendation: PostgreSQL

Key Factors:
- Strong ACID compliance for user data
- Team has SQL expertise
- Proven scalability with proper indexing
- Better for relational user data patterns

Trade-off Accepted:
- Less flexibility for schema changes
- Mitigation: Use JSONB for extensible fields

Decision Matrix: .aiwg/decisions/database-selection.md
ADR: .aiwg/architecture/adr-015-user-db.md"
```

### Quick Comparison

```
User: "Compare options for API gateway"

Skill generates:
- Kong vs AWS API Gateway vs Nginx
- Weighted criteria comparison
- Quick recommendation

Output:
"API Gateway Comparison:

| Criteria | Kong | AWS GW | Nginx |
|----------|------|--------|-------|
| Features | 5 | 4 | 3 |
| Cost | 3 | 4 | 5 |
| Ops Effort | 3 | 5 | 2 |
| Flexibility | 5 | 3 | 5 |
| Weighted | 4.1 | 4.0 | 3.8 |

Recommendation: Kong (slight edge)
Key: