patterns-technical-decisions

What this skill does

# 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 constraints-and-decisions.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 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](references/DECISION-RECORD.md) for full ADR format, consequences, and dependency tracking.

## constraints-and-decisions.md Output

Decisions go in `constraints-and-decisions.md` with this structure:

```markdown
# Constraints and Decisions: {feature_id}

## Summary

| ID | Decision | Choice | Rationale |
|----|----------|--------|-----------|
| D-001 | Auth mechanism | JWT | Stateless, scalable |
| D-002 | Session storage | PostgreSQL | Existing stack |

---

## Decision 1: [Title]

[Full decision record]

---

## Dependencies

| Decision | Depends On | Impacts |
|----------|------------|---------|
| D2 | D1 | Session table schema |
```

## Brownfield Alignment

Always check existing stack first:

| Scenario | Alignment | Action |
|----------|-----------|--------|
| Existing dep solves problem | High | Prefer reuse |
| New dep, same ecosystem | Medium | Document justification |
| New dep, different ecosystem | Low | Strong justification needed |
| Conflicting with existing | None | Avoid or escalate |

## Quality Checklist

Before finalizing:

**Evaluation:**
- [ ] At least 2-3 alternatives considered
- [ ] Criteria weighted by project context
- [ ] Each option has pros/cons
- [ ] Brownfield alignment assessed

**Documentation:**
- [ ] Context explains WHY decision is needed
- [ ] Rationale connects to specific criteria
- [ ] Trade-offs explicitly documented
- [ ] Constitution alignment checked
- [ ] Dependencies between decisions mapped

## Common Mistakes

### Single Option "Evaluation"
❌ "We evaluated Option A and chose it"
✅ "We compared Option A, Option B, and Option C against weighted criteria"

### Shiny Object Syndrome
❌ Choosing newest technology because it's trending
✅ Require strong justification for unfamiliar dependencies over existing stack

### Vague Rationale
❌ "We chose JWT because it's better"
✅ "We chose JWT because: stateless (fits our scale), team familiarity (3/4 devs), ecosystem support"

### Ignoring Team Skills
❌ Choosing Rust for a Python team without accounting for learning curve
✅ Weight team familiarity criterion appropriately in evaluation matrix

### Missing Trade-offs
❌ Only listing positives of chosen option
✅ Explicitly document what was given up: "Trade-off: JWT requires token refresh handling"

### Orphan Decisions
❌ Decisions documented in isolation
✅ Map decision dependencies: "D2 (session storage) depends on D1 (auth mechanism)"

### Constitution Blindness
❌ Making decisions that violate project principles
✅ Check alignment with constitution before finalizing