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

constraints-and-decisions.md Output

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

# 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