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 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:

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 for full ADR format, consequences, and dependency tracking.

research.md Output

Decisions go in research.md with this structure:

Research: {feature_id}

Summary

Decision 1: [Title]

[Full decision record]

Dependencies

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