Decision Frameworks (Meta-Skill)
Structured approaches for making engineering decisions with confidence and traceability.
Installation
OpenClaw / Moltbot / Clawbot
npx clawhub@latest install decision-frameworks
When to Use
- Choosing between libraries, frameworks, or tools
- Facing a build-vs-buy decision
- Selecting an architecture pattern (monolith vs microservices, SQL vs NoSQL, etc.)
- Multiple valid options exist and the team needs alignment
- Prioritizing a backlog or technical roadmap
- Documenting a significant technical decision for future reference
Decision Matrix Template
Use a weighted scoring matrix when comparing 3+ options across measurable criteria.
| Criteria |
Weight |
Option A |
Option B |
Option C |
| Performance |
5 |
4 (20) |
3 (15) |
5 (25) |
| Developer Experience |
4 |
5 (20) |
4 (16) |
3 (12) |
| Community Support |
3 |
5 (15) |
3 (9) |
2 (6) |
| Learning Curve |
3 |
3 (9) |
4 (12) |
2 (6) |
| Cost |
2 |
5 (10) |
3 (6) |
4 (8) |
| Total |
|
74 |
58 |
57 |
How to use:
- List criteria relevant to the decision
- Assign weights (1-5) based on project priorities
- Score each option per criterion (1-5)
- Multiply score x weight, sum per option
- Highest total wins — but sanity-check the result against gut feel
Build vs Buy Framework
Follow this decision tree:
Is it a core differentiator for your product?
├── YES → Build it (own the competitive advantage)
└── NO
├── Does a mature, well-maintained solution exist?
│ ├── YES → Buy / adopt it
│ └── NO → Build, but keep it minimal
└── Is the integration cost higher than building?
├── YES → Build
└── NO → Buy / adopt
Factor comparison:
| Factor |
Build |
Buy / Adopt |
| Maintenance cost |
Ongoing — your team owns it |
Vendor/community maintains it |
| Customization |
Unlimited flexibility |
Limited to extension points |
| Time to market |
Slower — development required |
Faster — ready-made |
| Team expertise |
Must have or acquire skills |
Abstracted away |
| Long-term cost |
Scales with internal capacity |
License/subscription fees |
| Vendor lock-in risk |
None |
Medium to high |
| Security control |
Full audit capability |
Dependent on vendor transparency |
Library / Framework Selection
Evaluate candidate libraries against these criteria before adopting:
| Criterion |
What to Check |
Red Flag |
| Maintenance activity |
Commits in last 90 days, open issues trend |
No commits in 6+ months |
| Community size |
GitHub stars, npm weekly downloads, Discord/forum |
< 1k weekly downloads for critical lib |
| Bundle size |
Bundlephobia, tree-shaking support |
> 50 KB gzipped for a utility lib |
| TypeScript support |
Built-in types vs DefinitelyTyped, type quality |
No types or outdated @types |
| Breaking change history |
Changelog, semver adherence, migration guides |
Frequent majors without guides |
| License |
OSI-approved, compatible with your project |
AGPL in a SaaS product, no license |
| Security audit |
Snyk/Socket score, CVE history, dependency depth |
Known unpatched CVEs |
| Documentation quality |
Getting started guide, API reference, examples |
README-only, no examples |
Quick heuristic: If you cannot replace the library within one sprint, treat the decision as a one-way door (see Reversibility Check below).
Architecture Decision Framework
Use these tradeoff tables when choosing between architectural approaches.
Monolith vs Microservices
| Factor |
Monolith |
Microservices |
| Complexity |
Low at start, grows over time |
High from day one |
| Deployment |
Single artifact |
Independent per service |
| Team scaling |
Harder beyond 10-15 engineers |
Enables autonomous teams |
| Data consistency |
ACID transactions |
Eventual consistency, sagas |
| Debugging |
Single process, easy tracing |
Distributed tracing required |
| Best when |
Early-stage, small team, MVP |
Proven domain boundaries, scale needs |
SQL vs NoSQL
| Factor |
SQL (Relational) |
NoSQL (Document/Key-Value) |
| Schema |
Strict, enforced |
Flexible, schema-on-read |
| Relationships |
Native joins, foreign keys |
Denormalized, application-level joins |
| Scaling |
Vertical (read replicas help) |
Horizontal by design |
| Consistency |
Strong (ACID) |
Tunable (eventual to strong) |
| Query flexibility |
Ad-hoc queries, aggregations |
Limited to access patterns |
| Best when |
Complex relations, reporting |
High write volume, flexible schema |
REST vs GraphQL
| Factor |
REST |
GraphQL |
| Simplicity |
Simple, well-understood |
Schema definition required |
| Over/under-fetching |
Common — multiple endpoints |
Clients request exact fields |
| Caching |
HTTP caching built-in |
Requires custom caching layer |
| Tooling |
Mature ecosystem |
Growing — Apollo, Relay, urql |
| Versioning |
URL or header versioning |
Schema evolution, deprecation |
| Best when |
CRUD APIs, public APIs |
Complex UIs, mobile + web clients |
SSR vs CSR vs SSG
| Factor |
SSR |
CSR |
SSG |
| Initial load |
Fast (HTML from server) |
Slow (JS bundle parse) |
Fastest (pre-built HTML) |
| SEO |
Excellent |
Poor without hydration |
Excellent |
| Best when |
Personalized pages |
Dashboards, SPAs |
Blogs, docs, marketing |
Monorepo vs Polyrepo
| Factor |
Monorepo |
Polyrepo |
| Code sharing |
Trivial — same repo |
Requires published packages |
| CI/CD complexity |
Needs smart filtering (Turborepo) |
Simple per-repo pipelines |
| Best when |
Shared libs, aligned releases |
Independent teams, different stacks |
Priority Matrices — RICE Scoring
Score and rank features/tasks:
RICE Score = (Reach x Impact x Confidence) / Effort
| Factor |
Scale |
| Reach |
Number of users/events affected per quarter |
| Impact |
3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal |
| Confidence |
100% = high, 80% = medium, 50% = low |
| Effort |
Person-weeks (or person-sprints) |
MoSCoW Method
| Category |
Meaning |
Budget Target |
| Must |
Non-negotiable for this release |
~60% of effort |
| Should |
Important but not critical |
~20% of effort |
| Could |
Desirable if time permits |
~15% of effort |
| Won't |
Explicitly out of scope (this time) |
~5% (planning) |
Reversibility Check
Classify every significant decision as a one-way or two-way door.
| Aspect |
One-Way Door (Type 1) |
Two-Way Door (Type 2) |
| Definition |
Irreversible or very costly to undo |
Easily reversed with low cost |
| Examples |
Database engine migration, public API contract, language rewrite |
UI framework for internal tool, feature flag experiment, library swap behind interface |
| How to identify |
Would reverting require > 1 sprint of rework? Data migration? Customer communication? |
Can you revert with a config change, flag toggle, or single PR? |
| Approach |
Invest in analysis, prototype, get stakeholder sign-off |
Decide fast, ship, measure, iterate |
| Time to decide |
Days to weeks — thorough evaluation |
Hours — bias toward action |
Rule of thumb: Wrap risky choices behind interfaces/abstractions. This converts many one-way doors into two-way doors by isolating the implementation from consumers.
ADR Template
Document significant decisions using a lightweight Architecture Decision Record.
# ADR-NNNN: [Short Title]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
## Context
What is the problem or situation that motivates this decision?
Include constraints, requirements, and forces at play.
## Decision
What is the change being proposed or adopted?
State the decision clearly and concisely.
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Tradeoff 1]
- [Tradeoff 2]
### Risks
- [Risk and mitigation]
Store in docs/adr/ or decisions/. Number sequentially. Never delete — mark superseded. Review during onboarding and quarterly audits.
Anti-Patterns
| Anti-Pattern |
Description |
Counter |
| Analysis Paralysis |
Endless evaluation, no decision made |
Set a decision deadline; use the matrix |
| HiPPO |
Highest Paid Person's Opinion overrides data |
Require data or a scored matrix for all options |
| Sunk Cost Fallacy |
Continuing because of past investment, not future value |
Evaluate options as if starting fresh today |
| Bandwagon Effect |
Choosing because "everyone uses it" |
Score against your actual criteria |
| Premature Optimization |
Optimizing before measuring or validating need |
Profile first; optimize only proven bottlenecks |
| Resume-Driven Development |
Picking tech to pad a resume, not to solve the problem |
Align choices with team skills and project goals |
| Not Invented Here |
Rejecting external solutions out of pride |
Run the Build vs Buy framework honestly |
NEVER Do
- NEVER skip writing down the decision — undocumented decisions get relitigated endlessly
- NEVER decide by committee without a single owner — assign a DRI (Directly Responsible Individual)
- NEVER treat all decisions as equal weight — classify by reversibility and impact first
- NEVER ignore second-order effects — ask "and then what?" at least twice
- NEVER lock in without an exit plan — define how you would migrate away before committing
- NEVER conflate familiarity with superiority — evaluate on criteria, not comfort
- NEVER defer a one-way door decision indefinitely — the cost of delay often exceeds the cost of a wrong choice
1---2name: decision-frameworks3description: Structured decision-making patterns for common engineering choices — library selection, architecture, build vs buy, prioritization, reversibility analysis, and ADRs. Use when choosing between tools, architectures, or approaches, or when documenting technical decisions.4---5
6# Decision Frameworks (Meta-Skill)
7
8Structured approaches for making engineering decisions with confidence and traceability.
9
10
11## Installation
12
13### OpenClaw / Moltbot / Clawbot
14
15```bash
16npx clawhub@latest install decision-frameworks
17```
18
19
20---
21
22## When to Use
23
24- Choosing between libraries, frameworks, or tools
25- Facing a build-vs-buy decision
26- Selecting an architecture pattern (monolith vs microservices, SQL vs NoSQL, etc.)
27- Multiple valid options exist and the team needs alignment
28- Prioritizing a backlog or technical roadmap
29- Documenting a significant technical decision for future reference
30
31---
32
33## Decision Matrix Template
34
35Use a weighted scoring matrix when comparing 3+ options across measurable criteria.
36
37| Criteria | Weight | Option A | Option B | Option C |
38|----------------------|--------|----------|----------|----------|
39| Performance | 5 | 4 (20) | 3 (15) | 5 (25) |
40| Developer Experience | 4 | 5 (20) | 4 (16) | 3 (12) |
41| Community Support | 3 | 5 (15) | 3 (9) | 2 (6) |
42| Learning Curve | 3 | 3 (9) | 4 (12) | 2 (6) |
43| Cost | 2 | 5 (10) | 3 (6) | 4 (8) |
44| **Total** | | **74** | **58** | **57** |
45
46**How to use:**
47
481. List criteria relevant to the decision
492. Assign weights (1-5) based on project priorities
503. Score each option per criterion (1-5)
514. Multiply score x weight, sum per option
525. Highest total wins — but sanity-check the result against gut feel
53
54---
55
56## Build vs Buy Framework
57
58Follow this decision tree:
59
60```
61Is it a core differentiator for your product?
62├── YES → Build it (own the competitive advantage)
63└── NO
64 ├── Does a mature, well-maintained solution exist?
65 │ ├── YES → Buy / adopt it
66 │ └── NO → Build, but keep it minimal
67 └── Is the integration cost higher than building?
68 ├── YES → Build
69 └── NO → Buy / adopt
70```
71
72**Factor comparison:**
73
74| Factor | Build | Buy / Adopt |
75|----------------------|--------------------------------|---------------------------------|
76| Maintenance cost | Ongoing — your team owns it | Vendor/community maintains it |
77| Customization | Unlimited flexibility | Limited to extension points |
78| Time to market | Slower — development required | Faster — ready-made |
79| Team expertise | Must have or acquire skills | Abstracted away |
80| Long-term cost | Scales with internal capacity | License/subscription fees |
81| Vendor lock-in risk | None | Medium to high |
82| Security control | Full audit capability | Dependent on vendor transparency |
83
84---
85
86## Library / Framework Selection
87
88Evaluate candidate libraries against these criteria before adopting:
89
90| Criterion | What to Check | Red Flag |
91|--------------------------|----------------------------------------------------|------------------------------------|
92| Maintenance activity | Commits in last 90 days, open issues trend | No commits in 6+ months |
93| Community size | GitHub stars, npm weekly downloads, Discord/forum | < 1k weekly downloads for critical lib |
94| Bundle size | Bundlephobia, tree-shaking support | > 50 KB gzipped for a utility lib |
95| TypeScript support | Built-in types vs DefinitelyTyped, type quality | No types or outdated @types |
96| Breaking change history | Changelog, semver adherence, migration guides | Frequent majors without guides |
97| License | OSI-approved, compatible with your project | AGPL in a SaaS product, no license |
98| Security audit | Snyk/Socket score, CVE history, dependency depth | Known unpatched CVEs |
99| Documentation quality | Getting started guide, API reference, examples | README-only, no examples |
100
101**Quick heuristic:** If you cannot replace the library within one sprint, treat the decision as a one-way door (see Reversibility Check below).
102
103---
104
105## Architecture Decision Framework
106
107Use these tradeoff tables when choosing between architectural approaches.
108
109### Monolith vs Microservices
110
111| Factor | Monolith | Microservices |
112|---------------------|----------------------------------|--------------------------------------|
113| Complexity | Low at start, grows over time | High from day one |
114| Deployment | Single artifact | Independent per service |
115| Team scaling | Harder beyond 10-15 engineers | Enables autonomous teams |
116| Data consistency | ACID transactions | Eventual consistency, sagas |
117| Debugging | Single process, easy tracing | Distributed tracing required |
118| Best when | Early-stage, small team, MVP | Proven domain boundaries, scale needs |
119
120### SQL vs NoSQL
121
122| Factor | SQL (Relational) | NoSQL (Document/Key-Value) |
123|---------------------|----------------------------------|--------------------------------------|
124| Schema | Strict, enforced | Flexible, schema-on-read |
125| Relationships | Native joins, foreign keys | Denormalized, application-level joins |
126| Scaling | Vertical (read replicas help) | Horizontal by design |
127| Consistency | Strong (ACID) | Tunable (eventual to strong) |
128| Query flexibility | Ad-hoc queries, aggregations | Limited to access patterns |
129| Best when | Complex relations, reporting | High write volume, flexible schema |
130
131### REST vs GraphQL
132
133| Factor | REST | GraphQL |
134|---------------------|----------------------------------|--------------------------------------|
135| Simplicity | Simple, well-understood | Schema definition required |
136| Over/under-fetching | Common — multiple endpoints | Clients request exact fields |
137| Caching | HTTP caching built-in | Requires custom caching layer |
138| Tooling | Mature ecosystem | Growing — Apollo, Relay, urql |
139| Versioning | URL or header versioning | Schema evolution, deprecation |
140| Best when | CRUD APIs, public APIs | Complex UIs, mobile + web clients |
141
142### SSR vs CSR vs SSG
143
144| Factor | SSR | CSR | SSG |
145|---------------------|------------------------|------------------------|-----------------------------|
146| Initial load | Fast (HTML from server) | Slow (JS bundle parse) | Fastest (pre-built HTML) |
147| SEO | Excellent | Poor without hydration | Excellent |
148| Best when | Personalized pages | Dashboards, SPAs | Blogs, docs, marketing |
149
150### Monorepo vs Polyrepo
151
152| Factor | Monorepo | Polyrepo |
153|---------------------|----------------------------------|--------------------------------------|
154| Code sharing | Trivial — same repo | Requires published packages |
155| CI/CD complexity | Needs smart filtering (Turborepo) | Simple per-repo pipelines |
156| Best when | Shared libs, aligned releases | Independent teams, different stacks |
157
158---
159
160## Priority Matrices — RICE Scoring
161
162Score and rank features/tasks:
163
164```
165RICE Score = (Reach x Impact x Confidence) / Effort
166```
167
168| Factor | Scale |
169|------------|--------------------------------------------------------|
170| Reach | Number of users/events affected per quarter |
171| Impact | 3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal |
172| Confidence | 100% = high, 80% = medium, 50% = low |
173| Effort | Person-weeks (or person-sprints) |
174
175### MoSCoW Method
176
177| Category | Meaning | Budget Target |
178|--------------|------------------------------------------------|----------------|
179| **Must** | Non-negotiable for this release | ~60% of effort |
180| **Should** | Important but not critical | ~20% of effort |
181| **Could** | Desirable if time permits | ~15% of effort |
182| **Won't** | Explicitly out of scope (this time) | ~5% (planning) |
183
184---
185
186## Reversibility Check
187
188Classify every significant decision as a one-way or two-way door.
189
190| Aspect | One-Way Door (Type 1) | Two-Way Door (Type 2) |
191|------------------|-------------------------------------|-------------------------------------|
192| Definition | Irreversible or very costly to undo | Easily reversed with low cost |
193| Examples | Database engine migration, public API contract, language rewrite | UI framework for internal tool, feature flag experiment, library swap behind interface |
194| How to identify | Would reverting require > 1 sprint of rework? Data migration? Customer communication? | Can you revert with a config change, flag toggle, or single PR? |
195| Approach | Invest in analysis, prototype, get stakeholder sign-off | Decide fast, ship, measure, iterate |
196| Time to decide | Days to weeks — thorough evaluation | Hours — bias toward action |
197
198**Rule of thumb:** Wrap risky choices behind interfaces/abstractions. This converts many one-way doors into two-way doors by isolating the implementation from consumers.
199
200---
201
202## ADR Template
203
204Document significant decisions using a lightweight Architecture Decision Record.
205
206```markdown
207# ADR-NNNN: [Short Title]
208
209## Status
210[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
211
212## Context
213What is the problem or situation that motivates this decision?
214Include constraints, requirements, and forces at play.
215
216## Decision
217What is the change being proposed or adopted?
218State the decision clearly and concisely.
219
220## Consequences
221
222### Positive
223- [Benefit 1]
224- [Benefit 2]
225
226### Negative
227- [Tradeoff 1]
228- [Tradeoff 2]
229
230### Risks
231- [Risk and mitigation]
232```
233
234Store in `docs/adr/` or `decisions/`. Number sequentially. Never delete — mark superseded. Review during onboarding and quarterly audits.
235
236---
237
238## Anti-Patterns
239
240| Anti-Pattern | Description | Counter |
241|--------------------------|------------------------------------------------------|---------------------------------------------|
242| Analysis Paralysis | Endless evaluation, no decision made | Set a decision deadline; use the matrix |
243| HiPPO | Highest Paid Person's Opinion overrides data | Require data or a scored matrix for all options |
244| Sunk Cost Fallacy | Continuing because of past investment, not future value | Evaluate options as if starting fresh today |
245| Bandwagon Effect | Choosing because "everyone uses it" | Score against your actual criteria |
246| Premature Optimization | Optimizing before measuring or validating need | Profile first; optimize only proven bottlenecks |
247| Resume-Driven Development | Picking tech to pad a resume, not to solve the problem | Align choices with team skills and project goals |
248| Not Invented Here | Rejecting external solutions out of pride | Run the Build vs Buy framework honestly |
249
250---
251
252## NEVER Do
253
2541. **NEVER skip writing down the decision** — undocumented decisions get relitigated endlessly
2552. **NEVER decide by committee without a single owner** — assign a DRI (Directly Responsible Individual)
2563. **NEVER treat all decisions as equal weight** — classify by reversibility and impact first
2574. **NEVER ignore second-order effects** — ask "and then what?" at least twice
2585. **NEVER lock in without an exit plan** — define how you would migrate away before committing
2596. **NEVER conflate familiarity with superiority** — evaluate on criteria, not comfort
2607. **NEVER defer a one-way door decision indefinitely** — the cost of delay often exceeds the cost of a wrong choice
johnalbertini14-glitch