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:

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:

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

| ID | Decision | Choice | Rationale |
|----|----------|--------|-----------|
| D1 | Auth mechanism | JWT | Stateless, scalable |
| D2 | 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:

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

Anti-Patterns