# Decision Framework

Comprehensive checklist before committing to complex solutions.

## Requirements Check

Validate that complexity addresses real, current needs.

- [ ] **Can you state the actual requirement in one sentence?**
  - If not: Requirements are unclear, gather more context
  - If yes: Proceed to verify

- [ ] **Is this requirement validated with users/stakeholders?**
  - Source: User research, stakeholder approval, or product spec?
  - If assumption: Validate before building

- [ ] **Does the requirement exist today or "might exist someday"?**
  - Today: Proceed with validation
  - Someday: Apply YAGNI - build when needed

- [ ] **What's the cost of being wrong about this requirement?**
  - Low cost: Start simple, iterate
  - High cost: Validate thoroughly first

## Alternatives Check

Ensure you've explored simpler options.

- [ ] **Have you listed at least 2 simpler alternatives?**
  - Standard library solution
  - Proven third-party library
  - Simpler architectural pattern
  - Direct implementation without abstraction

- [ ] **Have you tried the simplest approach first?**
  - If no: Why not? Time pressure isn't sufficient justification
  - If yes: What specific limitation did you hit?

- [ ] **Can you articulate why simpler approaches fail?**
  - Vague discomfort: Not sufficient
  - "Might not scale": Measure first
  - Specific technical limitation: Document it

- [ ] **Have you checked if the problem is already solved?**
  - Search npm/crates.io/PyPI for existing solutions
  - Check framework documentation for built-in features
  - Ask: "Is this a solved problem?"

## Constraint Check

Verify constraints are real, not assumed.

- [ ] **What breaks with the simple approach?**
  - Be specific: Which requirement? Which scenario?
  - If "nothing specific": Choose simple approach

- [ ] **Is the constraint real or assumed?**
  - Real: Measured, tested, validated
  - Assumed: "Might be slow", "Could be a problem", "Best practice says"
  - Test assumptions before building for them

- [ ] **Can the constraint be changed?**
  - Technical constraints: Often negotiable
  - Business constraints: Sometimes based on outdated assumptions
  - Political constraints: Navigate carefully, but challenge when appropriate

- [ ] **Who validated this constraint?**
  - You: Verify with others
  - Stakeholder: Confirm understanding
  - Documentation: Check if still current
  - "Everyone knows": Verify, might be outdated

## Cost Check

Evaluate long-term maintenance burden.

- [ ] **What's the maintenance burden of this complexity?**
  - How many LOC?
  - How many dependencies?
  - How many edge cases?
  - How often will this need updates?

- [ ] **Do we have expertise to maintain this?**
  - Team has experience: Lower risk
  - Team learning: Higher risk, needs documentation
  - Will depend on one person: Bus factor risk

- [ ] **What's the ramp-up time for new team members?**
  - Simple/standard patterns: Days
  - Custom/complex patterns: Weeks or months
  - Is the complexity worth the onboarding cost?

- [ ] **What's the cost of being wrong?**
  - Easy to change: Low risk, can experiment
  - Hard to change: High risk, validate thoroughly
  - Irreversible: Maximum risk, need strong justification

## Reversibility Check

Prefer decisions that can be changed later.

- [ ] **Can we start simple and add complexity later?**
  - Usually: Yes - this is the preferred path
  - Sometimes: Architectural decisions harder to reverse
  - Rarely: Truly irreversible (database choice, language choice)

- [ ] **What's the cost of changing direction?**
  - Low (<1 day): Experiment freely
  - Medium (1 week): Validate first, change if needed
  - High (>1 week): Requires strong justification

- [ ] **Is this decision reversible?**
  - Reversible: Start simple, learn, iterate
  - Irreversible: Invest in thorough validation
  - Document why if choosing complex approach for reversible decision

- [ ] **What would convince us to reverse this decision?**
  - Define success/failure criteria upfront
  - Set review timeline
  - Avoid sunk cost fallacy

## Scale Check

Don't optimize for scale you don't have.

- [ ] **What's the current scale?**
  - Users: 10? 1,000? 1,000,000?
  - Requests/sec: 1? 100? 10,000?
  - Data size: KB? GB? TB?

- [ ] **What scale does this solution target?**
  - Match current scale first
  - Optimize when measurements show need

- [ ] **What's the growth timeline?**
  - Weeks: Plan for scale now
  - Months: Build for 10x current, refactor at 100x
  - Years: Build for current, refactor when needed
  - Unknown: Build for current scale

- [ ] **Have you measured the performance bottleneck?**
  - No measurement: Premature optimization
  - Measured: Optimize the actual bottleneck
  - Assumed: Test assumption first

## Security Check

Security complexity requires special validation.

- [ ] **What's the threat model?**
  - Who are you protecting against?
  - What assets are at risk?
  - What's the impact of compromise?

- [ ] **Does this security measure address a real threat?**
  - Real: Documented, likely, high-impact
  - Theoretical: Low priority
  - Paranoia: Probably unnecessary

- [ ] **Is this a solved problem in security?**
  - Auth, crypto, secrets management: Use proven libraries
  - Custom security: Requires security expert review

- [ ] **What's the cost of getting security wrong?**
  - User data exposure: Use proven solutions
  - Low risk: Can be more experimental
  - Regulatory: Consult compliance expert

## Team Check

Complexity affects team velocity and morale.

- [ ] **Does the team understand this solution?**
  - Yes: Lower risk
  - Partially: Needs documentation
  - No: Training required or consider simpler approach

- [ ] **Is this pattern used elsewhere in the codebase?**
  - Yes: Consistency is valuable
  - No: Inconsistency has a cost, needs justification

- [ ] **Will the team thank you or curse you in 6 months?**
  - Thank you: Clear, maintainable, appropriate
  - Curse you: Clever, complex, hard to modify

- [ ] **What happens if the expert leaves?**
  - Well-documented: Manageable
  - Tribal knowledge: Bus factor risk
  - Documented externally (framework): Lower risk

## Integration Check

Consider ecosystem and dependencies.

- [ ] **How many dependencies does this add?**
  - 0-1: Low risk
  - 2-5: Medium, evaluate maintenance
  - 6+: High, consider consolidation

- [ ] **Are dependencies actively maintained?**
  - Check last commit, issue response time
  - Consider: Age, popularity, team size
  - Unmaintained: Risk or opportunity to fork

- [ ] **What's the total dependency tree size?**
  - Use `npm ls` or equivalent
  - Large trees = more security surface, slower installs
  - Consider: Tree-shakeable alternatives

- [ ] **Does this lock us into a specific ecosystem?**
  - Framework-specific: Consider portability cost
  - Standard/portable: Easier to migrate later
  - Vendor lock-in: Requires strong business justification

## Documentation Check

Complex solutions need clear documentation.

- [ ] **Can you explain why in 2 sentences?**
  - Yes: Good sign
  - No: May be too complex or poorly understood

- [ ] **Is there a simpler explanation you're avoiding?**
  - "It's just better": Not sufficient
  - "Best practice": For what context?
  - "More flexible": For what use case?

- [ ] **What will you document?**
  - Why this approach (most important)
  - How it works
  - When to modify/extend
  - When to replace

- [ ] **Who will maintain the documentation?**
  - Plan for keeping docs current
  - Outdated docs worse than no docs

## The Ultimate Question

- [ ] **If you had to maintain this code for the next 5 years, would you still choose this approach?**

If the answer is "no" or "I'm not sure", reconsider.

## Quick Decision Matrix

Use this matrix for fast assessment:

| Complexity | Justification Required |
|-----------|----------------------|
| **Low**: Standard library, proven pattern | None - proceed |
| **Medium**: Well-known framework, common pattern | Brief rationale in code comment |
| **High**: Custom abstraction, novel pattern | ADR with alternatives considered |
| **Very High**: Custom infrastructure, security-critical | ADR + external review + approval |

## When in Doubt

Default answers for common questions:

- **"Should we build or buy?"** → Buy (unless unique requirement validated)
- **"Should we abstract this?"** → Not yet (wait for 3rd use case)
- **"Should we optimize this?"** → Measure first (might not be bottleneck)
- **"Should we use this new technology?"** → Not for production (try in side project first)
- **"Should we make this configurable?"** → No (YAGNI - add when needed)

## Review Triggers

Set calendar reminders to review complex decisions:

- **1 month**: Quick check - still appropriate?
- **3 months**: Did we use the "flexibility" we built for?
- **6 months**: Is this paying off or causing pain?
- **12 months**: Keep, simplify, or replace?

## Red Flags

Stop and reconsider if you hear:

- "We might need it later"
- "It's more flexible"
- "It's best practice"
- "Everyone does it this way"
- "It's enterprise-ready"
- "I read about it on Hacker News"
- "It's the latest trend"
- "It looks good on my resume"

These are rationalization, not requirements.

## Green Flags

Complexity may be justified if:

- Measured performance bottleneck
- Proven scale requirement with timeline
- Regulatory compliance (validated with legal)
- Security threat model (validated with security team)
- Integration contract (external system requirement)
- Team expertise (already fluent, not learning)

Even then, choose the simplest solution that meets the requirement.

## Remember

**The best code is no code.**
**The second best code is boring code.**
**The worst code is clever code.**

Choose boring, simple, proven solutions until you have concrete evidence otherwise.