Technical Decision Making

Technical Decision Making Skill

Purpose

Provide engineering managers with structured frameworks for making sound technical decisions, evaluating technologies, managing technical debt, and developing technical roadmaps.

Primary Bond

Agent: technical-strategy-agent Relationship: This skill provides ADR templates, evaluation frameworks, and decision tools that the technical-strategy-agent uses.

---

Templates

Architecture Decision Record (ADR)

# ADR-{NUMBER}: {TITLE}

## Status
{Proposed | Accepted | Deprecated | Superseded by ADR-XXX}

## Date
{YYYY-MM-DD}

## Context
{What is the issue that we're seeing that is motivating this decision?}

## Decision Drivers
- {driver 1}
- {driver 2}

## Considered Options
1. {Option 1}
2. {Option 2}
3. {Option 3}

## Decision Outcome
Chosen option: "{option X}", because {justification}.

### Positive Consequences
- {consequence 1}

### Negative Consequences
- {consequence 1}

## Pros and Cons of Options

### Option 1: {name}
| Aspect | Assessment |
|--------|------------|
| Effort | {Low/Medium/High} |
| Risk | {Low/Medium/High} |
| Team Fit | {score}/5 |
| Reversibility | {Easy/Hard} |

Good, because {argument}.
Bad, because {argument}.

## Links
- {Link to related ADR}
- {Link to documentation}

Technology Evaluation Matrix

technology_evaluation:
  template:
    candidate: "{Technology name}"
    evaluation_date: "{Date}"
    evaluator: "{Name}"

  criteria:
    technical_fit:
      weight: 25%
      factors:
        - scalability_match: "1-5"
        - performance_requirements: "1-5"
        - security_compliance: "1-5"
      score: null

    team_readiness:
      weight: 20%
      factors:
        - current_expertise: "1-5"
        - learning_curve: "1-5"
        - hiring_market: "1-5"
      score: null

    ecosystem_maturity:
      weight: 20%
      factors:
        - community_size: "1-5"
        - documentation_quality: "1-5"
        - library_availability: "1-5"
      score: null

    operational:
      weight: 20%
      factors:
        - deployment_complexity: "1-5"
        - monitoring_support: "1-5"
        - maintenance_burden: "1-5"
      score: null

    cost:
      weight: 15%
      factors:
        - licensing: "1-5"
        - infrastructure: "1-5"
        - training: "1-5"
      score: null

  interpretation:
    4.5_plus: "Strong candidate - proceed"
    3.5_to_4.4: "Viable - address concerns"
    2.5_to_3.4: "Risky - significant gaps"
    below_2.5: "Not recommended"

Technical Debt Tracker

technical_debt_item:
  id: "TD-{NUMBER}"
  title: "{Short description}"
  category: "{architecture | code | infrastructure | testing | documentation}"
  quadrant: "{deliberate_prudent | deliberate_reckless | inadvertent_prudent | inadvertent_reckless}"

  description: "{Detailed description}"
  created_date: "{Date}"
  owner: "{Team/Person}"

  impact:
    development_velocity: "{-X%}"
    reliability_risk: "{low | medium | high}"
    security_risk: "{low | medium | high}"

  effort:
    estimate: "{T-shirt: S/M/L/XL}"
    sprints: "{Number}"
    dependencies: ["{Other work}"]

  interest_rate: "{stable | increasing | decreasing}"

  recommendation:
    action: "{fix | defer | monitor | accept}"
    timeline: "{Q1 2025}"
    justification: "{Why this recommendation}"

  resolution:
    status: "{open | in_progress | resolved | wont_fix}"
    resolved_date: null
    notes: null

Technical Roadmap

technical_roadmap:
  year: 2025

  q1:
    theme: "Foundation"
    initiatives:
      - name: "Infrastructure modernization"
        priority: "P0"
        owner: "Platform team"
        dependencies: []
      - name: "Observability stack"
        priority: "P1"
        owner: "SRE"
        dependencies: ["Infrastructure modernization"]

  q2:
    theme: "Scale"
    initiatives:
      - name: "Database sharding"
        priority: "P0"
        owner: "Data team"
        dependencies: ["Infrastructure modernization"]

  q3:
    theme: "Velocity"
    initiatives:
      - name: "CI/CD improvements"
        priority: "P1"
        owner: "DevEx team"

  q4:
    theme: "Innovation"
    initiatives:
      - name: "Event-driven architecture"
        priority: "P2"
        owner: "Architecture team"

---

Decision Trees

Build vs Buy

Need identified
|
+-- Is this core to our business?
|   +-- Yes -> Lean toward Build
|   +-- No -> Continue
|
+-- Does a good solution exist?
|   +-- No -> Must Build
|   +-- Yes -> Continue
|
+-- Can we afford the buy option?
|   +-- No -> Must Build
|   +-- Yes -> Continue
|
+-- Is time-to-market critical?
|   +-- Yes -> Lean toward Buy
|   +-- No -> Continue
|
+-- Do we have the expertise to build?
    +-- Yes -> Evaluate total cost of ownership
    +-- No -> Buy (or hire first)

Architecture Pattern Selection

Team size and domain complexity
|
+-- Small team (<5), Simple domain
|   +-- Monolith
|
+-- Small team, Complex domain
|   +-- Modular Monolith
|
+-- Large team (10+), Complex domain
|   +-- Microservices (with caution)
|
+-- Variable load, Event-driven
|   +-- Serverless / Event-driven
|
+-- Strong audit requirements
    +-- Event Sourcing + CQRS

---

Anti-Patterns

anti_patterns:
  resume_driven_development:
    symptoms:
      - "Let's use X because it's cool"
      - "This will look great on our blog"
    remedy:
      - "Require business case for any new tech"
      - "Evaluate with scoring matrix"

  golden_hammer:
    symptoms:
      - "We use X for everything"
      - "X worked before, it'll work now"
    remedy:
      - "Match tool to problem domain"
      - "Regular tech radar reviews"

  not_invented_here:
    symptoms:
      - "We'll build our own database"
      - "Open source isn't good enough"
    remedy:
      - "Build vs Buy analysis required"
      - "TCO comparison mandatory"

  analysis_paralysis:
    symptoms:
      - "We've been evaluating for 6 months"
      - "Let's add one more option"
    remedy:
      - "Time-box decisions"
      - "Use decision framework"
      - "Accept 'good enough'"

---

Quick Reference Cards

Decision Time-Boxing

Tech Debt Quadrant

                    Reckless                Prudent
            +---------------------+---------------------+
Deliberate  | "We don't have time | "We must ship now   |
            |  for design"        |  and deal with      |
            |  -> Fix ASAP        |  consequences"      |
            |                     |  -> Plan paydown    |
            +---------------------+---------------------+
Inadvertent | "What's layering?"  | "Now we know how    |
            |  -> Training needed |  we should have     |
            |                     |  done it"           |
            |                     |  -> Refactor next   |
            +---------------------+---------------------+

DORA Metrics

---

Troubleshooting

---

Validation Rules

input_validation:
  decision_context:
    type: string
    min_length: 20
    required: true

  constraints:
    type: object
    properties:
      budget: { type: string }
      timeline: { type: string }
      team_expertise: { type: array }
    required: false

  current_stack:
    type: array
    items: { type: string }
    required: false

---

Resources

Books:

• Designing Data-Intensive Applications - Martin Kleppmann
• Building Evolutionary Architectures - Ford, Parsons, Kua
• Fundamentals of Software Architecture - Richards, Ford
• The Staff Engineer's Path - Tanya Reilly

Standards:

• Architecture Decision Records (ADR) - Michael Nygard
• DORA Metrics - Accelerate research

Technical Decision Making

ADR Template

• Title
• Status
• Context
• Decision
• Consequences

Decision Criteria

• Technical feasibility
• Team capability
• Timeline impact
• Scalability needs
• Maintenance cost