magnus919_agent-skills/cncf-landscape/references/decision-framework.md

Landscape-backed decision framework

The goal is not to find the most famous project. The goal is to identify a small set of candidates that could satisfy the user's constraints, explain what the catalog evidence does and does not establish, and choose the cheapest next validation step.

1. Decision intake

Write these down before filtering:

Dimension	Questions
Capability	What outcome must the technology provide? What is explicitly out of scope?
Workload	Protocols, data shape, latency/throughput, durability, tenancy, failure behavior, and peak conditions?
Boundary	Cloud, self-hosted, air-gapped, managed service, Kubernetes, VMs, edge, or mixed?
Integration	Existing APIs, languages, storage, identity, networking, observability, and deployment tooling?
Operations	Who owns it at 02:00? What skills, on-call burden, upgrade cadence, and support path are acceptable?
Governance	License policy, security review, data residency, supply-chain rules, and required project governance?
Decision economics	Time to first useful result, migration cost, recurring cost, lock-in, and reversibility?
Evidence bar	What must be proven before a proof of concept, production approval, or adoption decision?

Mark each requirement as hard, preferred, or unknown. Do not silently convert an unstated preference into a hard filter.

2. Candidate discovery and filtering

Use the Landscape category/subcategory and search fields to find a broad candidate set, then filter in this order:

1. Capability relevance: Does the project actually address the requested outcome? A category label is only a discovery hint.
2. Hard constraints: Remove candidates that fail explicit deployment, license, maturity, language, or repository requirements. Explain every exclusion.
3. Evidence completeness: Prefer candidates whose current documentation, source, release, security, and operations evidence can be inspected. Missing evidence is a risk, not proof of failure.
4. Operational fit: Compare the work the team must operate, integrate, secure, upgrade, and recover. This usually requires sources outside the Landscape.
5. Ecosystem signals: Use repository activity, release recency, contributors, and CNCF lifecycle as directional evidence. Keep each signal separate so a large star count cannot hide weak operational fit.

A shortlist should be bounded enough to compare. Three to five candidates is a useful working target, not a quota; keep more when the decision genuinely has several distinct solution families.

3. Comparison dimensions

For each finalist, fill in a table like this:

Dimension	Evidence	Judgment
Capability fit	What the project and current docs explicitly provide	How directly it satisfies the stated outcome
Deployment fit	Supported runtime and topology	Whether it fits the target boundary without an unproven adapter
Operational burden	Components, dependencies, upgrades, backups, failure recovery	Who can operate it and what must be built around it
Integration fit	APIs, protocols, SDKs, identity, observability	Migration and adoption friction
Lifecycle and governance	CNCF maturity plus project release/security/governance evidence	Risk appropriate to the user's horizon
Community and ecosystem	Repository and ecosystem signals	How much external evidence exists, without treating popularity as support
License and policy	Exact repository/dependency/license sources	Whether review is required before adoption
Reversibility	Data and API portability, exit path, migration options	Cost of being wrong
Unknowns	Unverified assumptions and missing evidence	The next probe or experiment

Use labels such as observed, inferred, and unknown in the evidence or judgment column. Do not collapse them into one confidence number unless the user supplies the weighting model.

4. Recommendation shape

A decision-safe recommendation contains:

1. Conditional preference: “Choose A if the hard constraints remain X and Y.”
2. Credible alternative: “Choose B instead if Z matters more.”
3. Exclusions: What was filtered out and why, including candidates that looked popular but failed a real constraint.
4. Trade-offs: The principal operational, integration, security, economic, and lock-in costs.
5. Disproof test: The smallest experiment or source check that could overturn the preference.
6. Adoption boundary: What is safe to prototype now, what needs review, and what should not be promised yet.

Do not write “best,” “production-ready,” “most secure,” or “standard” without a source and scope that supports the claim. Prefer “best fit for the stated constraints” and name the constraints.

5. Validation plan

Turn the recommendation into a bounded sequence:

• verify the project's current installation and compatibility documentation;
• build the smallest representative path using the user's real interface or protocol;
• exercise a realistic workload, tenant/security boundary, and failure mode;
• measure latency, throughput, resource use, recovery, and operator steps against explicit thresholds;
• test upgrades, rollback, data/API export, and observability;
• review license, security advisories, dependency provenance, and ownership;
• record the result in an ADR or technology-radar entry.

A successful catalog query is discovery evidence. It is not a successful proof of concept.