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

Decision Type	Time Box	Reversibility
Tool selection	1 week	High
Framework choice	2 weeks	Medium
Architecture pattern	1 month	Low
Platform migration	1 quarter	Very Low

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

Metric	Elite	High	Medium	Low
Deployment Frequency	On-demand	Daily-Weekly	Weekly-Monthly	Monthly+
Lead Time	<1 hour	<1 day	<1 week	1 month+
Change Failure Rate	<5%	5-10%	10-15%	15%+
Recovery Time	<1 hour	<1 day	<1 week	1 month+

Troubleshooting

Problem	Root Cause	Solution
Decisions get reversed	Poor documentation	Use ADR template
Tech debt grows unchecked	No visibility	Track with debt template
Wrong tech choices	No evaluation process	Use scoring matrix
Roadmap not followed	Unclear priorities	P0/P1/P2 classification

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