tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.