When evaluating a third-party library or framework for a new feature, what does checking its 'capability fit' involve, and why is comparing feature checklists on vendor or project websites not enough on its own?

## What a capability-fit check verifies Capability fit is the process of verifying that a candidate library, framework, or off-the-shelf component actually solves your team's concrete problem, as opposed to merely appearing to solve it because a feature is listed on its homepage or README. ## The mechanism, step by step The mechanism, step by step, starts with translating your requirement into three to six specific scenarios drawn from real usage: not 'needs caching' but 'must serve a 10k-key hot set with sub-5ms p99 reads and support cross-instance invalidation within 200ms.' Each scenario is then walked through the candidate, ideally by building a small working prototype rather than reading documentation alone, because documentation describes intended behavior while a prototype reveals actual behavior, including undocumented limits, default timeouts, and error-handling quirks. Alongside functional scenarios, the check must cover non-functional capabilities that rarely appear on a feature list: - the **concurrency model** (does it block a thread, spawn its own pool, require you to manage backpressure?) - the **extension points** (can you plug in a custom serializer, retry policy, or auth provider?) - the **observability hooks** (does it expose metrics, structured logs, tracing spans, or is it a black box?) - the **configuration surface** (how many knobs exist, and do the defaults suit you?) Each gap found is then classified: | Gap class | What it says about the candidate | |---|---| | **hard blocker** | feature genuinely missing, no workaround | | **workaround needed** | achievable but adds code and maintenance burden you now own | | **acceptable gap** | edge case you can live without | ## Why a feature checklist is a marketing artifact This exists because feature checklists are marketing artifacts, not specifications. A checklist entry like 'supports pub/sub' or 'exactly-once delivery' tells you nothing about semantics: - does exactly-once mean the broker deduplicates for you, or does it mean at-least-once delivery with deduplication pushed onto your application via idempotency keys? - Does 'supports async validation' mean it truly runs off the UI thread, or does it just expose a Promise-based API that still blocks internally under load? Teams that skip a real fit check and select based on the marketing page or a quick tutorial often discover the gap only once the component is wired into production code, by which point the cost of reversing the decision has multiplied. ## The trade-off: time versus risk The trade-off is **time versus risk**. A rigorous capability-fit check - building prototypes for two or three realistic scenarios per candidate, across two or three candidates - can cost anywhere from a few days to a couple of sprint-weeks before a single line of the real feature is built. That competes with delivery pressure, since stakeholders see 'evaluating libraries' as pre-work rather than progress. The opposing failure mode is **over-evaluation**: some teams turn fit-checking into an open-ended research project, prototyping every edge case for every candidate, which becomes its own form of decision paralysis and can cost more than picking a reasonable default and adapting later. The right calibration scales depth to the cost of being wrong: a component embedded deep in the data layer or touching every request deserves a multi-day prototype; a peripheral utility used in one non-critical code path does not. ## Failure modes in production Failure modes show up in predictable ways in production. 1. A **queue library** selected because it 'supported ordering' turns out to guarantee ordering only within a single partition, and the team discovers cross-partition reordering under load only after a customer-visible bug. 2. An **ORM** chosen because it 'supports complex queries' turns out to require dropping to raw SQL for the exact pattern the product needs, which then has to be retrofitted awkwardly around the ORM's transaction and connection-pooling assumptions. 3. A **form-validation library** advertised as supporting async validators serializes them internally, so validating ten fields concurrently takes ten times as long as expected, and the UI feels sluggish under real user input. In each case, the checklist item was technically true, but the fit was false, and the discovery happened after the component was load-bearing rather than during evaluation. ## A worked example: two caching candidates A concrete worked example: a team choosing between two caching technologies purely on the 'key-value cache' checklist item would see both as fitting equally. But their actual scenario also requires broadcasting cache-invalidation events to multiple service instances - a **pub/sub capability** one candidate supports natively (via publish/subscribe commands) and the other lacks entirely, having no notion of messaging beyond simple gets and sets. A checklist comparison of 'caching support' alone would miss this completely; only mapping the concrete invalidation-broadcast scenario onto each candidate surfaces the real differentiator, which is exactly what a prototype-driven fit check is designed to catch.