Decision Frameworks

Decision Frameworks (Meta-Skill)

Structured approaches for making engineering decisions with confidence and traceability.

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. CriteriaWeightOption AOption BOption CPerformance54 (20)3 (15)5 (25)Developer Experience45 (20)4 (16)3 (12)Community Support35 (15)3 (9)2 (6)Learning Curve33 (9)4 (12)2 (6)Cost25 (10)3 (6)4 (8)Total745857 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: FactorBuildBuy / AdoptMaintenance costOngoing — your team owns itVendor/community maintains itCustomizationUnlimited flexibilityLimited to extension pointsTime to marketSlower — development requiredFaster — ready-madeTeam expertiseMust have or acquire skillsAbstracted awayLong-term costScales with internal capacityLicense/subscription feesVendor lock-in riskNoneMedium to highSecurity controlFull audit capabilityDependent on vendor transparency

Library / Framework Selection

Evaluate candidate libraries against these criteria before adopting: CriterionWhat to CheckRed FlagMaintenance activityCommits in last 90 days, open issues trendNo commits in 6+ monthsCommunity sizeGitHub stars, npm weekly downloads, Discord/forum< 1k weekly downloads for critical libBundle sizeBundlephobia, tree-shaking support> 50 KB gzipped for a utility libTypeScript supportBuilt-in types vs DefinitelyTyped, type qualityNo types or outdated @typesBreaking change historyChangelog, semver adherence, migration guidesFrequent majors without guidesLicenseOSI-approved, compatible with your projectAGPL in a SaaS product, no licenseSecurity auditSnyk/Socket score, CVE history, dependency depthKnown unpatched CVEsDocumentation qualityGetting started guide, API reference, examplesREADME-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

FactorMonolithMicroservicesComplexityLow at start, grows over timeHigh from day oneDeploymentSingle artifactIndependent per serviceTeam scalingHarder beyond 10-15 engineersEnables autonomous teamsData consistencyACID transactionsEventual consistency, sagasDebuggingSingle process, easy tracingDistributed tracing requiredBest whenEarly-stage, small team, MVPProven domain boundaries, scale needs

SQL vs NoSQL

FactorSQL (Relational)NoSQL (Document/Key-Value)SchemaStrict, enforcedFlexible, schema-on-readRelationshipsNative joins, foreign keysDenormalized, application-level joinsScalingVertical (read replicas help)Horizontal by designConsistencyStrong (ACID)Tunable (eventual to strong)Query flexibilityAd-hoc queries, aggregationsLimited to access patternsBest whenComplex relations, reportingHigh write volume, flexible schema

REST vs GraphQL

FactorRESTGraphQLSimplicitySimple, well-understoodSchema definition requiredOver/under-fetchingCommon — multiple endpointsClients request exact fieldsCachingHTTP caching built-inRequires custom caching layerToolingMature ecosystemGrowing — Apollo, Relay, urqlVersioningURL or header versioningSchema evolution, deprecationBest whenCRUD APIs, public APIsComplex UIs, mobile + web clients

SSR vs CSR vs SSG

FactorSSRCSRSSGInitial loadFast (HTML from server)Slow (JS bundle parse)Fastest (pre-built HTML)SEOExcellentPoor without hydrationExcellentBest whenPersonalized pagesDashboards, SPAsBlogs, docs, marketing

Monorepo vs Polyrepo

FactorMonorepoPolyrepoCode sharingTrivial — same repoRequires published packagesCI/CD complexityNeeds smart filtering (Turborepo)Simple per-repo pipelinesBest whenShared libs, aligned releasesIndependent teams, different stacks

Priority Matrices — RICE Scoring

Score and rank features/tasks: RICE Score = (Reach x Impact x Confidence) / Effort FactorScaleReachNumber of users/events affected per quarterImpact3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimalConfidence100% = high, 80% = medium, 50% = lowEffortPerson-weeks (or person-sprints)

MoSCoW Method

CategoryMeaningBudget TargetMustNon-negotiable for this release~60% of effortShouldImportant but not critical~20% of effortCouldDesirable if time permits~15% of effortWon'tExplicitly out of scope (this time)~5% (planning)

Reversibility Check

Classify every significant decision as a one-way or two-way door. AspectOne-Way Door (Type 1)Two-Way Door (Type 2)DefinitionIrreversible or very costly to undoEasily reversed with low costExamplesDatabase engine migration, public API contract, language rewriteUI framework for internal tool, feature flag experiment, library swap behind interfaceHow to identifyWould reverting require > 1 sprint of rework? Data migration? Customer communication?Can you revert with a config change, flag toggle, or single PR?ApproachInvest in analysis, prototype, get stakeholder sign-offDecide fast, ship, measure, iterateTime to decideDays to weeks — thorough evaluationHours — 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-PatternDescriptionCounterAnalysis ParalysisEndless evaluation, no decision madeSet a decision deadline; use the matrixHiPPOHighest Paid Person's Opinion overrides dataRequire data or a scored matrix for all optionsSunk Cost FallacyContinuing because of past investment, not future valueEvaluate options as if starting fresh todayBandwagon EffectChoosing because "everyone uses it"Score against your actual criteriaPremature OptimizationOptimizing before measuring or validating needProfile first; optimize only proven bottlenecksResume-Driven DevelopmentPicking tech to pad a resume, not to solve the problemAlign choices with team skills and project goalsNot Invented HereRejecting external solutions out of prideRun 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