patterns-technical-decisions

# Making Technical Decisions

## Purpose

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.

## 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](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 are accepted

**Quick Comparison Format:**

| Option | Pros | Cons | Alignment | Verdict |
|--------|------|------|-----------|---------|
| Option A | + Fast, + Simple | - New dep | High | **Best** |
| Option B | + Familiar | - Slow | Medium | Good |
| Option C | + Feature-rich | - Complex | Low | Poor |

### Phase 3: Document

Record decisions in ADR format for future maintainers.

**Quick Decision Record:**

```markdown
## Decision: [Title]

**Status**: Proposed | Accepted | Deprecated

**Context**: [Why this decision is needed]

**Decision**: [What we chose]

**Rationale**: [Why - connect to criteria]

**Trade-offs Accepted**: [What we gave up]
```

See [DECISION-RECORD.md](DECISION-RECORD.md) for full ADR format, consequences, and dependency tr