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