framework-fit-analysis

name	framework-fit-analysis
description	Use when choosing, replacing, or justifying a framework, library, SDK, runtime, database, UI kit, or platform by fit: constraints, team skill, ecosystem maturity, migration cost, operability, performance, security, and exit cost. Do NOT use for routine dependency hygiene (use `dependency-architecture`), documenting an accepted decision (use `architecture-decision-records`), or framework-specific implementation work.
license	MIT
compatibility	Portable technology-selection discipline for application frameworks, libraries, SDKs, platforms, runtimes, data stores, and agent tooling.
allowed-tools	Read Grep
metadata	{"schema_version":"4","version":"1.0.0","type":"capability","category":"engineering","domain":"architecture/technology-selection","scope":"portable","owner":"skill-graph-maintainer","freshness":"2026-05-11","drift_check":"{\"last_verified\":\"2026-05-11\"}","eval_artifacts":"present","eval_state":"unverified","routing_eval":"absent","stability":"experimental","keywords":"[\"framework fit\",\"technology selection\",\"library choice\",\"SDK evaluation\",\"platform evaluation\",\"migration cost\",\"exit cost\",\"operability\",\"ecosystem maturity\",\"build vs buy\"]","examples":"[\"should we use Next.js server actions, route handlers, or a separate API service for this workflow?\",\"evaluate whether adding this charting library is worth it\",\"compare Supabase, Firebase, and custom Postgres for this project under real constraints\",\"we want to replace this framework - what fit analysis should happen before an ADR?\"]","anti_examples":"[\"audit installed packages for duplication and supply-chain risk\",\"write the ADR after we chose the framework\",\"implement this feature in the framework we already selected\",\"profile a slow page and optimize bottlenecks\"]","relations":"{\"boundary\":[{\"skill\":\"dependency-architecture\",\"reason\":\"dependency-architecture governs dependency graph shape and package boundaries; framework-fit-analysis evaluates a candidate technology decision\"},{\"skill\":\"architecture-decision-records\",\"reason\":\"architecture-decision-records records accepted decisions; framework-fit-analysis compares options before acceptance\"},{\"skill\":\"performance-engineering\",\"reason\":\"performance-engineering measures and optimizes actual behavior; framework-fit-analysis weighs expected performance among selection criteria\"},{\"skill\":\"refactor\",\"reason\":\"refactor changes existing code structure; framework-fit-analysis decides whether a larger technology shift is justified\"}],\"related\":[\"architecture-decision-records\",\"dependency-architecture\",\"performance-engineering\",\"owasp-security\"],\"verify_with\":[\"architecture-decision-records\",\"dependency-architecture\"]}","portability":"{\"readiness\":\"scripted\",\"targets\":[\"skill-md\"]}","lifecycle":"{\"stale_after_days\":180,\"review_cadence\":\"quarterly\"}","skill_graph_source_repo":"https://github.com/jacob-balslev/skill-graph","skill_graph_protocol":"Skill Metadata Protocol v3","skill_graph_project":"Skill Graph","skill_graph_canonical_skill":"skills/framework-fit-analysis/SKILL.md"}

Framework Fit Analysis

Coverage

Evaluate technology fit before adoption, replacement, or standardization. Covers requirement fit, constraints, ecosystem maturity, maintenance health, team skill, integration cost, migration path, performance envelope, security posture, operational burden, lock-in, exit cost, and decision recording.

Philosophy

Technology choice is context-dependent. "Best" without constraints is marketing. A good fit analysis makes tradeoffs explicit enough that a team can accept the costs knowingly.

Do not confuse popularity with fit. Do not let a narrow implementation preference choose a durable platform. The right output is a recommendation plus consequences, not a ranking table with fake precision.

Method

1. State the job the technology must do.
2. List hard constraints: runtime, hosting, data, compliance, team, budget, timeline.
3. Define evaluation criteria and weights qualitatively: must-have, important, nice-to-have.
4. Compare credible options, including staying put.
5. Assess migration and exit costs.
6. Identify operational ownership and failure modes.
7. Recommend one path with accepted tradeoffs.
8. Hand off to architecture-decision-records if the decision is durable.

Evals

This skill ships a comprehension-eval artifact at examples/evals/framework-fit-analysis.json. The checklist below is the authoring gate for technology-fit decisions; the eval file is the grader surface.

Verification

• The recommendation is tied to explicit project constraints
• "Do nothing" or "keep current stack" was considered when real
• Migration and exit costs are named
• Operational ownership is named
• Performance and security claims are evidence-backed or marked uncertain
• The decision can be reversed only with known cost
• Follow-up ADR is proposed for durable choices

Do NOT Use When

Use instead	When