--- name: decision-frameworks model: reasoning description: 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. ---

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:

1. List criteria relevant to the decision
2. Assign weights (1-5) based on project priorities
3. Score each option per criterion (1-5)
4. Multiply score x weight, sum per option
5. 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.

...