DECISIONS.md
Decision-Making Framework for Technical Choices
A Sr Dev's value isn't knowing the right answer - it's knowing the right questions.
The Core Questions
Before any significant decision, answer these:
1. What problem are we actually solving?
- State it in one sentence
- If you can't, the problem isn't clear yet
- "Build X" is not a problem statement. "Users need Y" is.
2. What are the constraints?
- Time: When does this need to ship?
- Resources: Just Eddie? Team? Budget?
- Technical: What must we integrate with? What's already built?
- Knowledge: What do we know how to do vs. need to learn?
3. What are the options?
- Always generate at least 2-3 options
- Include "do nothing" or "defer" as a valid option
- Include the "boring" option (proven tech, simple approach)
4. What are the tradeoffs?
For each option:
- Pros: What does this give us?
- Cons: What does this cost us?
- Risks: What could go wrong?
- Reversibility: Can we change our mind later?
5. What's the simplest thing that could work?
- Start here. Add complexity only when forced.
- "We might need X later" is not a reason to build X now.
6. What would make this the wrong choice?
- Pre-mortem thinking
- If we learn X, does this decision still hold?
- What assumptions are we making?
Decision Types
Reversible vs. Irreversible
Reversible (move fast, course-correct):
- Library/framework choices (usually)
- UI patterns
- Most feature implementations
- File structure
Irreversible (slow down, think hard):
- Database schema (core entities)
- Authentication/authorization model
- Public API contracts
- Data architecture (what you store, how you access it)
- Platform choice (iOS vs. Android vs. Web vs. all)
Now vs. Later
Decide Now:
- Blocking current work
- Affects other decisions downstream
- Cost of delay > cost of being wrong
Decide Later:
- More information coming
- Not blocking anything
- Reversible anyway
Platform Decision Framework
Specific to Eddie's common question: iOS/Android/Web
Questions to Ask
Where are your users?
- Consumer app → Mobile-first likely
- Business tool → Web-first likely
- Creative tool → Depends on workflow
What native capabilities do you need?
- Camera, GPS, sensors → Native or React Native
- Files, offline → Native handles better
- Just data display/input → Web/PWA fine
What's your iteration speed need?
- Web deploys instantly
- Mobile has app store delays
- If learning fast matters, web first
What's your maintenance capacity?
- Each platform = ongoing cost
- Cross-platform reduces but doesn't eliminate
Common Patterns
| Situation | Recommendation |
|---|---|
| Validating idea fast | Web (PWA if mobile feel needed) |
| Consumer app, broad reach | React Native or Flutter |
| Performance-critical native features | Native iOS + Native Android |
| Internal tool / small audience | Web |
| Existing web app, adding mobile | React Native (share logic) |
Technology Selection Framework
The Boring Technology Principle
"Choose boring technology." - Dan McKinley
Every new technology has a learning curve, unknown failure modes, and integration cost. You have a limited "innovation budget."
Spend innovation tokens on:
- Your core differentiator
- Problems with no boring solution
Use boring tech for:
- Everything else
Questions for Technology Choices
Who else uses this in production?
- Large-scale usage = battle-tested
- "Hot new thing" = you're the beta tester
What's the community/support like?
- Stack Overflow answers?
- Active maintenance?
- Documentation quality?
Does it fit the existing stack?
- Consistency has value
- Adding a new language/framework has cost
What's the escape hatch?
- If this doesn't work, how do we migrate?
- Avoid lock-in on critical paths
Documentation Template
When making a significant decision, document it:
## Decision: [Title]
**Date**: YYYY-MM-DD
**Status**: Proposed / Accepted / Superseded
**Project**: [Project Name]
### Context
What situation are we in? What forced this decision?
### Options Considered
1. **Option A**: [Description]
- Pros: ...
- Cons: ...
2. **Option B**: [Description]
- Pros: ...
- Cons: ...
### Decision
We chose [Option X] because [reasoning].
### Consequences
- We will need to...
- This means we can't easily...
- We're accepting the tradeoff of...
### Review Trigger
Revisit this decision if: [conditions that would change the calculus]
Anti-Patterns in Decision Making
❌ Analysis Paralysis: Researching forever, never deciding → Set a timebox. Decide with 70% confidence.
❌ Hype-Driven Development: Choosing tech because it's trending → Ask: "Who's using this in production at scale?"
❌ Resume-Driven Development: Choosing tech to learn something cool → Ask: "Does this serve the project or just me?"
❌ Premature Optimization: Building for scale you don't have → Ask: "What's the actual load today? In 6 months?"
❌ Sunk Cost Commitment: Sticking with bad choice because you invested → Ask: "If starting fresh today, would I choose this?"
Remember
"The best decision is often the one that preserves optionality."
When uncertain:
- Defer irreversible decisions
- Make reversible bets
- Build to learn, not to last
- Ship and iterate