Architecture Decision Framework

Make architecture decisions using decision matrices and iterative refinement.

Why This Skill Exists

Most architecture advice jumps to "the best solution" without understanding the problem. This skill flips the order: understand the business context first, present options, ask clarifying questions, then decide.

When to Use

• Choosing between multiple implementation approaches
• Evaluating trade-offs between speed, quality, and cost
• Deciding on technology stack components
• When the team lacks consensus on the right path
• When user pushes back on a plan that seems too complex

When Not to Use

• Decision is obvious (e.g., "should I use TypeScript?")
• Non-architectural decisions (naming, formatting)
• User already has a clear preference
• Only one viable option

The Methodology

Phase 1: Understand the Problem

Before presenting options, clarify:

User request
  → Business goal?
  → Constraints (time, team, budget)?
  → Timeline (MVP vs long-term)?
  → Reversible vs irreversible?
  → Team expertise?

MVP vs Production Quick-Check

If constraints are unambiguous, skip the full matrix:

Short-circuit rules: Still document the decision (Phase 5). Offer to revisit if requirements change.

Phase 2: Present Options with Decision Matrix

Present 2-4 options with a structured comparison:

| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| **MVP Speed** | ✅ Fast | ⚠️ Medium | ❌ Slow |
| **Long-term** | ⚠️ Tech debt | ✅ Maintainable | ✅ Maintainable |
| **Complexity** | ✅ Low | ⚠️ Medium | ❌ High |
| **Reversibility** | ✅ Easy | ⚠️ Medium | ❌ Hard |
| **Team Expertise** | ✅ Known | ⚠️ Learning curve | ❌ New |

For weighted scoring with criteria priorities, see references/scoring.md.

Phase 3: Ask Clarifying Questions (With a Cap)

Ask 3-5 questions max, then make a preliminary recommendation:

1. Questions 1-2: Always ask (core constraints)
2. Questions 3-5: Ask if needed (refine details)
3. After question 5: Recommend with assumptions stated

When you've hit the cap:

"I've asked enough questions. Based on what you've told me — [assumptions] — I recommend Option B. My reasoning: [rationale]. Tell me if I've misunderstood."

Phase 4: Make Recommendation with Rationale

## Recommendation: Option [X]

**Why:** [business reason], [trade-off acknowledged]
**Consequences:** [positive], [positive], [known limitation]
**Revisit when:** [trigger for reconsideration]

Phase 5: Document as ADR

# ADR-XXX: [Title]

**Status:** Proposed | Accepted | Deprecated | Superseded
**Context:** What is the issue motivating this decision?
**Decision:** What is the proposed change?
**Consequences:** What becomes easier or more difficult?
**Alternatives:** What other options and why not chosen?
**Date:** When this was decided

Phase 6: Iterate Based on Feedback

Recommendation made → User feedback → Refine → Confirm → Document

Iteration patterns:

Common Pitfalls

1. Jumping to solutions — presenting options before understanding the problem
2. Analysis paralysis — too many options (keep to 2-4)
3. Ignoring reversibility — not considering cost of changing later
4. Over-asking — more than 5 questions before recommending
5. Skipping ADR — not documenting why you chose a path