patterns-technical-decisions

# Making Technical Decisions

## Overview

Provide a complete framework for technology decisions: evaluate alternatives against consistent criteria, make informed choices, and document decisions so future maintainers understand WHY choices were made.

## When to Use

- Choosing between technology options (libraries, frameworks, services)
- When research.md requires "NEEDS CLARIFICATION" resolution
- Documenting architectural decisions for the team
- When spec or plan requires technology choice justification
- Evaluating existing stack vs new dependencies
- Any decision with long-term maintenance implications

## When NOT to Use

- **Trivial changes** - No architectural impact, obvious solution
- **Decisions already documented** - Existing ADR covers the scenario
- **Emergency hotfixes** - Document decision post-facto, don't block fix
- **Pure implementation details** - Internal code structure without external impact
- **Reversible choices** - Easily changed later without consequence

## Decision Workflow

```
1. EVALUATE    →    2. DECIDE    →    3. DOCUMENT
   Options           Best fit          For posterity
```

### Phase 1: Evaluate Options

For each decision point, consider 2-3 alternatives minimum.

**Quick Criteria Reference:**

| Criterion | Key Question |
|-----------|--------------|
| **Fit** | Does it solve the problem fully? |
| **Complexity** | How hard to implement and maintain? |
| **Team Familiarity** | Does the team know this tech? |
| **Ecosystem** | Good docs, active community? |
| **Scalability** | Will it grow with the project? |
| **Security** | Good security posture? |
| **Cost** | Total cost of ownership? |
| **Brownfield Alignment** | Fits existing stack? |

See [EVALUATION-MATRIX.md](references/EVALUATION-MATRIX.md) for detailed criteria, scoring, and technology category comparisons.

### Phase 2: Decide

Score options against weighted criteria. Document:
- Which option scores best
- Why criteria were weighted as they were
- What trade-offs