slashskills

Write a decision doc when you're stuck between approaches. Forces a pick instead of endless deliberation.

Phase 1: Frame the Decision

Get these from the user or extract from conversation:

What's the decision? — One sentence. "Which auth provider to use" not "thinking about auth stuff."
Why now? — What's blocked until this is decided? Urgency changes the answer.
What are the options? — 2-4 options. More than 4 means you haven't filtered enough.
What are the constraints? — Budget, timeline, team size, existing tech, non-negotiables.

If the user says "I'm stuck between X and Y," you already have 1 and 3. Don't re-ask.

Phase 2: Define the Criteria

Before comparing options, agree on what matters. Ask the user to rank these or suggest your own based on context:

Common criteria (pick 3-5 that matter for this decision):

Time to implement
Long-term maintenance burden
Cost (money)
Team familiarity / learning curve
Scalability / performance
Flexibility to change later
Community / ecosystem / docs
User experience impact
Security implications
Reversibility — how hard is it to switch if this is wrong?

Reversibility is the tiebreaker. When two options are close, pick the one that's easier to undo. Irreversible decisions deserve more deliberation. Reversible ones deserve speed.

Phase 3: Write the Doc

DECISION — [title]
════════════════════════════════════

CONTEXT
[2-3 sentences. What we're building, why this decision matters now,
what's blocked until we decide.]

CONSTRAINTS
- [constraint 1]
- [constraint 2]
- [constraint 3]

OPTIONS

┌─────────────────────────────────────────────┐
│ Option A: [name]                            │
├─────────────────────────────────────────────┤
│ How it works: [1-2 sentences]               │
│ Upside: [strongest argument]                │
│ Downside: [strongest argument against]      │
│ Effort: [S/M/L]                             │
│ Reversibility: [easy/medium/hard]           │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ Option B: [name]                            │
├─────────────────────────────────────────────┤
│ How it works: [1-2 sentences]               │
│ Upside: [strongest argument]                │
│ Downside: [strongest argument against]      │
│ Effort: [S/M/L]                             │
│ Reversibility: [easy/medium/hard]           │
└─────────────────────────────────────────────┘

[Option C if needed — same format]

RECOMMENDATION
[Pick one. Say why in 2-3 sentences. Be direct.]

WHAT WE'RE GIVING UP
[Name the tradeoff explicitly. What's the cost of this choice?
This forces honesty about what you're sacrificing.]

════════════════════════════════════

Phase 4: Anti-Patterns

Decisions stall for predictable reasons. Call them out:

"Let's do both" — No. Doing both means you're not deciding. If you genuinely need both, build one first and the other later. Which one first? That's the decision.

"Let's prototype and see" — Sometimes valid. Usually a delay tactic. If a 2-hour spike will genuinely resolve uncertainty, do it. If you'll still be unsure after, decide now.

"It depends" — On what? Name the specific variable. If you can name it, you can evaluate it. If you can't, you're stalling.

"What do other companies use?" — Useful data point, bad decision framework. You're not other companies. What matters is your constraints, your timeline, your team.

Bike-shedding — Spending an hour debating a decision that takes 30 minutes to reverse. If the decision is easily reversible, timebox to 10 minutes and pick.

Phase 5: After the Decision

Once decided:

Save the doc — Offer to write it as DECISIONS.md or docs/decisions/YYYY-MM-DD-[title].md
First action — What's the very first thing to do to execute this decision? Name it.
Kill the other options — Don't leave doors open. If you picked Clerk, stop evaluating NextAuth. Decision debt compounds.

Verify