gh-lyndonkl-claude/skills/adr-architecture/resources/methodology.md

ADR Methodology for Complex Decisions

Complex ADR Workflow

Copy this checklist and track your progress:

ADR Progress (Complex Decisions):
- [ ] Step 1: Identify decision pattern and scope
- [ ] Step 2: Conduct detailed analysis for each concern
- [ ] Step 3: Engage stakeholders and gather input
- [ ] Step 4: Build decision tree for related choices
- [ ] Step 5: Perform quantitative analysis and create ADR

Step 1: Identify decision pattern and scope

Determine which pattern applies to your decision (cascading, competing concerns, unknown unknowns, etc.). See Complex Decision Patterns for patterns and approaches.

Step 2: Conduct detailed analysis for each concern

For each competing concern (security, scalability, cost, compliance), analyze how alternatives address it. See Extended ADR Sections for analysis templates.

Step 3: Engage stakeholders and gather input

Identify all affected parties and gather their perspectives systematically. See Stakeholder Management for mapping and engagement techniques.

Step 4: Build decision tree for related choices

Map out cascading or interdependent decisions. See Decision Trees for Related Choices for structuring related ADRs.

Step 5: Perform quantitative analysis and create ADR

Use scoring matrices, cost modeling, or load testing to support decision. See Quantitative Analysis for methods and examples.

Complex Decision Patterns

Pattern 1: Cascading Decisions

When one architectural choice forces or constrains subsequent decisions.

Approach:

1. Create primary ADR for the main architectural decision
2. Create child ADRs for cascading decisions, referencing parent
3. Use "Related ADRs" field to link the chain

Example:

• ADR-100: Adopt Microservices Architecture (parent)
• ADR-101: Use gRPC for Inter-Service Communication (child - follows from ADR-100)
• ADR-102: Implement Service Mesh with Istio (child - follows from ADR-101)

Pattern 2: Competing Concerns

When decision must balance multiple competing priorities (cost vs performance, security vs usability).

Approach: Add Analysis Sections to standard ADR:

## Detailed Analysis

### Security Analysis
{How each alternative addresses security requirements}

### Performance Analysis
{Benchmarks, load tests, scalability projections}

### Cost Analysis
{TCO over 3 years, including hidden costs}

### Operational Complexity Analysis
{Team skill requirements, monitoring needs, on-call burden}

Pattern 3: Phased Decisions

When full solution is too complex to decide at once; need to make interim decision.

Approach:

1. Create ADR for Phase 1 decision
2. Add "Future Decisions" section listing what's deferred
3. Set review date to revisit (e.g., "Review in 6 months")

Example:

## Decision (Phase 1)
Start with managed PostgreSQL on RDS. Evaluate sharding vs Aurora vs NewSQL in 12 months.

## Future Decisions Needed
- ADR-XXX: Horizontal scaling strategy (by Q3 2025)
- ADR-XXX: Multi-region deployment approach (by Q4 2025)

Extended ADR Sections

When to Add Detailed Analysis Sections

Security Analysis - Add when:

• Decision affects authentication, authorization, or data protection
• Compliance requirements involved (SOC2, HIPAA, GDPR)
• Handling sensitive data

Performance Analysis - Add when:

• SLA commitments at stake
• Significant performance differences between alternatives
• Scalability is critical concern

Cost Analysis - Add when:

• Multi-year TCO differs significantly (>20%) between alternatives
• Hidden costs exist (operational overhead, training, vendor lock-in)
• Budget constraints are tight

Operational Complexity Analysis - Add when:

• Team skill gaps exist for some alternatives
• On-call burden varies significantly
• Monitoring/debugging complexity differs

Migration Analysis - Add when:

• Replacing existing system
• Need to maintain backward compatibility
• Rollback strategy is complex

Template for Extended Sections

## Security Analysis

### {Alternative A}
- **Threat model**: {What threats does this mitigate?}
- **Attack surface**: {What new vulnerabilities introduced?}
- **Compliance**: {How does this meet regulatory requirements?}
- **Score**: {1-5 rating}

### {Alternative B}
{Same structure}

### Security Recommendation
{Which alternative is strongest on security, and any mitigations needed}

Stakeholder Management

Identifying Stakeholders

Technical stakeholders:

• Engineering teams affected by the decision
• DevOps/SRE teams who will operate the solution
• Security team for compliance/security decisions
• Architecture review board (if exists)

Business stakeholders:

• Product managers (feature impact)
• Finance (budget implications)
• Legal/compliance (regulatory requirements)
• Executive sponsors (strategic alignment)

Getting Input

Pre-ADR phase:

1. Conduct stakeholder interviews to gather requirements and constraints
2. Share draft alternatives for early feedback
3. Identify concerns and dealbreakers

ADR draft phase:

1. Share draft ADR with key stakeholders for review
2. Hold working session to discuss controversial points
3. Revise based on feedback

Approval phase:

1. Present ADR at architecture review (if applicable)
2. Get sign-off from decision-makers
3. Communicate decision to broader team

Recording Stakeholder Positions

For controversial decisions, add:

## Stakeholder Positions

**Backend Team (Support):**
"PostgreSQL aligns with our SQL expertise and provides ACID guarantees we need."

**DevOps Team (Concerns):**
"Concerned about operational complexity of read replicas. Request 2-week training before launch."

**Finance (Neutral):**
"Within budget. Request quarterly cost reviews to ensure no overruns."

Decision Trees for Related Choices

When decision involves multiple related questions, use decision tree approach.

Example: Cloud Provider + Database Decision

Q1: Which cloud provider?
├─ AWS
│  ├─ Q2: Which database?
│  │  ├─ RDS PostgreSQL → ADR-042
│  │  ├─ Aurora → ADR-043
│  │  └─ DynamoDB → ADR-044
│
├─ GCP
│  └─ Q2: Which database?
│     ├─ Cloud SQL → ADR-045
│     └─ Spanner → ADR-046

Approach:

1. Create ADR for Q1 (cloud provider selection)
2. Create separate ADRs for Q2 based on Q1 outcome
3. Link ADRs using "Related ADRs" field

Quantitative Analysis

Cost-Benefit Matrix

For decisions with measurable trade-offs:

Alternative	Setup Cost	Annual Cost	Performance (QPS)	Team Velocity Impact	Risk Score
PostgreSQL	$10k	$36k	50k	+10% (familiar)	Low
MongoDB	$15k	$84k	100k	-20% (learning)	Medium
DynamoDB	$5k	$60k	200k	-15% (new patterns)	Medium

Decision Matrix with Weighted Criteria

When multiple factors matter with different importance:

## Weighted Decision Matrix

Criteria weights:
- Performance: 30%
- Cost: 25%
- Team Expertise: 20%
- Operational Simplicity: 15%
- Ecosystem Maturity: 10%

| Alternative | Performance | Cost | Team | Ops | Ecosystem | Weighted Score |
|-------------|-------------|------|------|-----|-----------|----------------|
| PostgreSQL  | 7/10        | 9/10 | 10/10| 8/10| 10/10     | **8.35**       |
| MongoDB     | 9/10        | 6/10 | 5/10 | 7/10| 8/10      | 7.10           |
| DynamoDB    | 10/10       | 7/10 | 4/10 | 9/10| 7/10      | 7.50           |

PostgreSQL scores highest on weighted criteria.

Scenario Analysis

For decisions under uncertainty, model different futures:

## Scenario Analysis

### Scenario 1: Rapid Growth (3x projections)
- PostgreSQL: Need expensive scaling (Aurora + sharding), $150k/yr
- DynamoDB: Handles easily, $120k/yr
- **Winner**: DynamoDB

### Scenario 2: Moderate Growth (1.5x projections)
- PostgreSQL: Read replicas sufficient, $60k/yr
- DynamoDB: Overprovisioned, $90k/yr
- **Winner**: PostgreSQL

### Scenario 3: Slow Growth (0.8x projections)
- PostgreSQL: Single instance sufficient, $40k/yr
- DynamoDB: Low usage still requires min provision, $70k/yr
- **Winner**: PostgreSQL

**Assessment**: PostgreSQL wins in 2 of 3 scenarios. Given our conservative growth estimates, PostgreSQL is safer bet.

Review and Update Process

When to Review ADRs

Scheduled reviews:

• High-stakes decisions: Review after 6 months
• Medium-stakes: Review after 12 months
• Check if consequences matched reality

Triggered reviews:

• Major change in context (team size, scale, requirements)
• Significant problems attributed to decision
• New technology emerges that changes trade-offs

How to Update ADRs

Never edit old ADRs. Instead:

1. Create new ADR that supersedes the old one
2. Update old ADR status to "Superseded by ADR-XXX"
3. New ADR should reference old one and explain what changed

Example:

# ADR-099: Migrate from PostgreSQL to CockroachDB

**Status:** Accepted
**Date:** 2026-03-15
**Supersedes:** ADR-042 (PostgreSQL decision)

## Context
ADR-042 chose PostgreSQL in 2024 when we had 5k users. We now have 500k users across 8 regions. PostgreSQL sharding has become operationally complex...

## What Changed
- Scale increased 100x beyond projections
- Multi-region deployment now required for latency
- Team size grew from 5 to 40 engineers (distributed systems expertise available)
...

Summary

For complex decisions:

• Break into multiple ADRs if needed (use cascading pattern)
• Add detailed analysis sections for critical factors
• Engage stakeholders early and document positions
• Use quantitative analysis (matrices, scenarios) to support intuition
• Plan for review and evolution over time

Remember: The best ADR is the one that helps future teammates understand "why" when reading it 2 years later.