technical-decision-recordlisted

<framework_overview> ## What This Is A structured approach to documenting technical decisions using ADRs (Architecture Decision Records). Ensures decisions are traceable, well-reasoned, and understood by the team. ## When to Use - Choosing between technologies or frameworks - Making architectural changes - Selecting third-party services - Changing established patterns - Any decision you'd want to reference later </framework_overview> <principles> ## Core Philosophy ### 1. DECISIONS ARE IMMUTABLE HISTORY Once made, an ADR is never modified—only superseded. This preserves the reasoning at the time, even if context changes later. ### 2. CONTEXT OVER CONCLUSION The "why" is more valuable than the "what." Future readers need to understand the constraints, options, and trade-offs that led to the decision. ### 3. BIAS TOWARD REVERSIBILITY Prefer decisions that can be changed later. Document the reversal cost for irreversible choices. ### 4. EXPLICIT OVER IMPLICIT If it wasn't written down, it wasn't decided. Verbal agreements don't count as architectural decisions. ### 5. TEAM OVER INDIVIDUAL Decisions should be reviewed by affected parties. Surprise decisions create resistance. </principles> <process> ## The Process ### Step 1: Define the Problem What are we deciding? Be specific. - "Which database for user data" not "database stuff" - Include the trigger: what prompted this decision? ### Step 2: List Constraints What limits our options? - Technical: performance, scalab