Technology Adoption

---




name: technology-adoption
description: Maps concrete project requirements to specific technology recommendations
  using domain-driven decision matrices, adoption risk scoring, and phased rollout
  strategies for selecting and leveraging technologies effectively.
license: MIT
compatibility: opencode
metadata:
  version: "1.0.0"
  domain: coding
  triggers: technology adoption, tech stack choice, how do i choose technology, select framework for my project, pick the right tool, technology decision, framework recommendation, technology leverage framework for my project
  archetypes:
  - tactical
  - generation
  anti_triggers:
  - brainstorming
  - vague ideation
  - code golf
  - over-engineering
  response_profile:
    verbosity: low
    directive_strength: high
    abstraction_level: operational
  role: implementation
  scope: implementation
  output-format: code
  content-types:
  - code
  - guidance
  - examples
  - do-dont
  related-skills: framework-selection, framework-utilization, software-architecture,
    hexagonal-architecture




---




# Technology Adoption and Leverage Framework

Maps concrete project requirements to specific technology recommendations using domain-driven decision matrices, adoption risk scoring, and phased rollout strategies. This skill helps teams choose technologies that match their actual needs (not hype) and then leverage them effectively by working with the ecosystem rather than against it.

## TL;DR Checklist

- [ ] Define 3-5 concrete requirements that constrain technology choices (NOT "scalable" or "maintainable")
- [ ] Map each requirement to specific technical capabilities, not brand names
- [ ] Score candidates using the adoption risk matrix — maturity, team fit, ecosystem health, lock-in potential
- [ ] Verify at least one production reference exists for the top candidate in your project domain
- [ ] Plan a phased rollout: spike → prototype → limited pilot → full adoption with rollback criteria
- [ ] Identify the 2-3 framework-specific patterns that unlock 80% of its value — ignore the rest initially

---

## When to Use

Use this skill when:

- Starting a new project and need to choose between competing technologies (e.g., Next.js vs. Remix vs. SvelteKit for a data-heavy dashboard)
- Evaluating whether to adopt a new technology that your team has never used before
- A project is struggling with its current technology stack and needs a structured re-evaluation
- Deciding whether to invest in learning an ecosystem deeply or keep surface-level knowledge across many
- Justifying a technology choice to stakeholders who care about business outcomes, not technical features
- Building a proof of concept that will determine the long-term technology direction

## When NOT to Use

- When leadership has already mandated a specific technology and there is no flexibility — use `framework-utilization` instead to focus on integration
- For language-level decisions (Python vs. Go vs. Rust) unless the team has no established preference — these are broader than technology adoption
- When the project is trivial (a single-page script, one-off automation) — structured adoption overhead exceeds benefits
- When you need help integrating a specific framework into your codebase — use `framework-utilization` for that

---

## Core Workflow

### Step 1: Define Constraint Requirements

Extract 3-5 concrete requirements from project context. Each requirement must be measurable and falsifiable. Vague requirements produce vague technology choices.

**Bad (vague):** "The app needs to be fast"
**Good (constrained):** "Page load time under 2 seconds on a mid-range mobile device (4G connection) with at least 500ms of JavaScript processing time available."

**Bad:** "Needs good developer experience"
**Good:** "A new graduate-level engineer should be able to add a CRUD endpoint in under 30 minutes using only official documentation."

**Required requirement categories** (pick the top 3-5 that apply):
- **Performance threshold** — throughput, latency, or resource constraints
- **Time-to-market** — weeks to production-ready minimum viable product
- **Team capacity** — current team skills and learning bandwidth
- **Operational complexity** — monitoring, deployment, debugging capabilities needed
- **Ecosystem needs** — specific libraries, integrations, or standards required

**Checkpoint:** Each requirement must have a numeric threshold. If you cannot write a test that validates it, the requirement is not yet concrete enough.

### Step 2: Map Requirements to Technical Capabilities

Translate each requirement into the specific technical capabilities needed from the technology. This bridges business needs and technical evaluation.

Example mapping for a real-time analytics dashboard:
```
Requirement: "Dashboard must refresh data every 5 seconds with <500ms latency"
→ Capability: Native WebSocket or Server-Sent Events support
→ Capability: Efficient state management for frequent updates
→ Capability: Data serialization optimized for small, frequent payloads

Requirement: "Team of 3 engineers with React experience, no GraphQL knowledge"
→ Capability: Strong React integration (or built-in frontend framework)
→ Capability: Auto-generated client SDK from backend types
→ Capability: Documentation quality that substitutes for expert training
```

**Checkpoint:** Every capability must be verifiable in the framework's documentation or source code. If you cannot confirm it exists, score the candidate lower regardless of its reputation.

### Step 3: Build Decision Matrix with Adoption Risk Scoring

For each candidate technology, compute an adoption risk score across four dimensions. Then calculate a weighted fit score against your requirements.

```python
from dataclasses import dataclass, field
from typing import Optional


@dataclass
class Requirement:
    name: str
    weight: float  # 0.0 - 1.0, must sum to 1.0
    threshold: str
    measurable: bool


@dataclass
class TechnologyCandidate:
    name: str
    version: str = ""
    description: str = ""


@dataclass
class AdoptionRiskScore:
    """Structured risk assessment for adopting a new technology."""

    maturity_score: int  # 1-5: established vs bleeding edge
    team_fit_score: int  # 1-5: how well it matches team skills/patterns
    ecosystem_health: int  # 1-5: active development, community, docs quality
    lock_in_risk: int  # 5 = low risk (easy to remove), 1 = high risk (deeply coupled)

    @property
    def average_score(self) -> float:
        return (self.maturity_score + self.team_fit_score +
                self.ecosystem_health + self.lock_in_risk) / 4.0

    @property
    def risk_level(self) -> str:
        avg = self.average_score
        if avg >= 4.5:
            return "LOW"
        if avg >= 3.5:
            return "MODERATE"
        if avg >= 2.5:
            return "ELEVATED"
        return "HIGH"


class TechnologyDecisionEngine:
    """Maps requirements to technology recommendations with risk scoring."""

    def __init__(self, requirements: list[Requirement]):
        total_weight = sum(r.weight for r in requirements)
        if abs(total_weight - 1.0) > 1e-9:
            raise ValueError(f"Requirements weights must sum to 1.0, got {total_weight:.4f}")
        self.requirements = {r.name: r for r in requirements}

    def score_candidate(
        self,
        candidate: TechnologyCandidate,
        capability_scores: dict[str, int],  # requirement_name -> 1-10
        adoption_risk: AdoptionRiskScore,
    ) -> dict:
        """Compute weighted fit and return full evaluation for a candidate."""

        fit_score = sum(
            self.requirements[name].weight * (score / 10)
            for name, score in capability_scores.items()
            if name in self.requirements
        ) * 10  # Normalize to 0-10 scale

        return {
            "candidate": candidate.name,
            "version": candidate.version,
            "weighted_fit": round(fit_score, 2),
            "adoption_risk": adoption_risk.risk_level,
            "adoption_risk_score": round(adoption_risk.average_score, 2),
            "capability_breakdown": capability_scores,
        }

    def rank_candidates(self, evaluations: list[dict]) -> list[dict]:
        """Sort candidates by fit score (descending), then risk level."""
        risk_order = {"LOW": 0, "MODERATE": 1, "ELEVATED": 2, "HIGH": 3}

        return sorted(
            evaluations,
            key=lambda e: (-e["weighted_fit"], risk_order.get(e["adoption_risk"], 99)),
        )
```

**Checkpoint:** Cross-validate the decision matrix with at least one team member who was not involved in building it. Discrepancies in scores reveal unclear requirements or biased assumptions.

### Step 4: Validate Against Production References

Every technology recommendation must be backed by evidence that it works in production for similar use cases. This is where reputation meets reality.

**Evidence sources to consult (in priority order):**
1. **Official case studies** — Does the framework vendor publish customer examples in your domain?
2. **GitHub trending repositories** — Search for active projects using the technology in your ecosystem
3. **Stack Overflow trends** — Growth vs. decline in question volume over 12 months indicates adoption trajectory
4. **Conference talks from production teams** — Real deployment stories, not marketing presentations
5. **Published benchmarks** — Independent performance comparisons with methodology transparency

**Red flags that should trigger immediate reconsideration:**
- Zero production case studies in your specific domain (not just "in production" but "handling similar data volumes/patterns")
- All community packages maintained by a single author with no recent commits
- Documentation that references outdated major versions without migration guides
- Major contributors publicly expressing dissatisfaction with the project direction

### Step 5: Plan Phased Rollout with Rollback Criteria

Technology adoption is a process, not an event. Define explicit milestones and exit criteria at each phase.

**Phase 1 — Technical Spike (1-2 weeks):**
- Build the single most challenging technical aspect of your intended use case
- Evaluate documentation quality during the spike — if it requires reverse-engineering source code, that's a real usability problem
- Document what worked and what didn't with specific code snippets

**Phase 2 — Prototype (2-4 weeks):**
- Build a minimal production-like system covering the core data flow
- Include actual deployment pipeline (CI/CD, monitoring setup)
- Measure development velocity compared to your baseline technology
- **Exit criterion:** If you cannot deploy the prototype in under 30 minutes of manual work, the operational complexity is too high

**Phase 3 — Limited Pilot (1-3 months):**
- Deploy to a single non-critical feature or service
- Monitor error rates, performance, and developer experience metrics
- Collect structured feedback from engineers using it daily
- **Exit criterion:** Production error rate below 0.5% and average bug fix time under 4 hours

**Phase 4 — Full Adoption (ongoing):**
- Migrate remaining services or features progressively
- Maintain rollback capability until migration is complete
- Document lessons learned for future technology decisions

```python
from dataclasses import dataclass
from datetime import date, timedelta


@dataclass
class RolloutMilestone:
    name: str
    duration_days: int
    exit_criteria: list[str]
    rollback_action: str  # What to do if criteria are not met


def plan_adoption_rollout(
    project_name: str,
    technology_name: str,
    team_size: int,
    criticality: str = "medium",  # low | medium | high
) -> list[RolloutMilestone]:
    """Generate a phased rollout plan based on project characteristics."""

    timeframes = {
        "low": {"spike": 5, "prototype": 10, "pilot": 14},
        "medium": {"spike": 7, "prototype": 14, "pilot": 30},
        "high": {"spike": 10, "prototype": 21, "pilot": 60},
    }

    t = timeframes.get(criticality, timeframes["medium"])

    return [
        RolloutMilestone(
            name="Technical Spike",
            duration_days=t["spike"],
            exit_criteria=[
                f"Core technical challenge resolved (documented with code examples)",
                "Documentation evaluated and gaps identified",
                f"Team of {team_size} engineers can build a minimal working example independently",
            ],
            rollback_action="Revert to previous technology; spike artifacts archived as reference",
        ),
        RolloutMilestone(
            name="Prototype",
            duration_days=t["prototype"],
            exit_criteria=[
                "Full deployment pipeline operational (CI/CD, monitoring, logging)",
                f"Average development time per feature under 2 hours for team of {team_size}",
                "Production error rate below 1% in prototype environment",
            ],
            rollback_action="Discard prototype; conduct post-mortem on adoption blockers",
        ),
        RolloutMilestone(
            name="Limited Pilot",
            duration_days=t["pilot"],
            exit_criteria=[
                "Production error rate below 0.5% over full pilot period",
                f"Average bug fix time under 4 hours for team of {team_size}",
                "At least 80% of engineering team reports neutral or positive experience in survey",
                "Monitoring and alerting coverage exceeds 90% of critical paths",
            ],
            rollback_action="Revert pilot feature; document specific issues that prevented successful adoption",
        ),
    ]
```

### Step 6: Identify Core Patterns That Unlock Ecosystem Value

Every technology has a core set of patterns that deliver disproportionate value. Learning these first prevents wasting time on edge cases. Then identify the ecosystem's extension mechanisms (plugins, middleware, hooks) and evaluate which ones deserve investment.

**Framework-specific pattern libraries by category:**
```
Web Frameworks:
  - Routing conventions and middleware ordering
  - Data validation and serialization patterns
  - Authentication/authorization flow (session vs. token-based)
  - Error handling middleware and custom error pages
  - Database connection pooling and query optimization

Data Processing:
  - Pipeline composition and transformation patterns
  - Memory management for large datasets (chunking, streaming)
  - Parallel processing and distributed execution
  - Schema validation and evolution strategies

Infrastructure/DevOps:
  - Configuration management (secrets, environments, feature flags)
  - Health check patterns and readiness probes
  - Graceful shutdown and connection draining
  - Observability integration (metrics, tracing, logging format)
```

**Checkpoint:** Before committing to any framework-specific pattern, verify it aligns with your team's existing architectural conventions. Fighting the framework's defaults is expensive; working with them delivers compounding returns.

---

## Implementation Patterns

### Pattern 1: Technology Decision Document Generator

Generates a structured decision document that captures requirements, analysis, and recommendation.

```python
from datetime import date


def generate_tech_decision_document(
    project_name: str,
    requirements: dict[str, str],
    candidates_evaluated: list[dict],
    recommended_candidate: str,
    reasoning: list[str],
    risks: list[str] = None,
    reviewers: list[str] = None,
) -> str:
    """Generate a technology decision document suitable for team review and archival."""

    lines = [
        f"# Technology Decision: {project_name}",
        "",
        f"**Date:** {date.today().isoformat()}  ",
        f"**Recommended Technology:** {recommended_candidate}  ",
        *(f"**Reviewers:** {', '.join(reviewers)}" if reviewers else ""),
        "",
        "---",
        "",
        "## Requirements",
    ]

    for name, description in requirements.items():
        lines.append(f"- **{name}:** {description}")

    lines.extend(["", "## Candidates Evaluated"])
    for candidate in candidates_evaluated:
        name = candidate["candidate"]
        fit = candidate.get("weighted_fit", "N/A")
        risk = candidate.get("adoption_risk", "N/A")
        version = candidate.get("version", "")
        lines.append(f"- `{name}` ({version}) — Fit: {fit}/10, Risk: {risk}")

    lines.extend([
        "",
        "## Recommendation",
        f"We recommend adopting **{recommended_candidate}** because:",
    ])

    for reason in reasoning:
        lines.append(f"1. {reason}")

    if risks:
        lines.extend(["", "## Known Risks"])
        for risk in risks:
            lines.append(f"- {risk}")

    lines.extend([
        "",
        f"**Next Steps:** Proceed to Technical Spike phase with exit criteria defined in rollout plan.",
    ])

    return "\n".join(lines) + "\n"
```

### Pattern 2: Ecosystem Health Monitor

Checks whether a technology's ecosystem is healthy enough for production use.

```python
import json


def assess_ecosystem_health(
    package_name: str,
    registry_data: dict,  # From npm/PyPI/Cargo/Maven API
    github_data: dict = None,
) -> dict:
    """Evaluate ecosystem health from available package metadata and GitHub data."""

    score = 0
    issues = []
    warnings = []

    # Check recent activity (last 90 days)
    last_published = registry_data.get("last_published", "")
    if last_published:
        from datetime import datetime, timedelta
        last_date = datetime.fromisoformat(last_published.replace("Z", "+00:00"))
        days_since = (datetime.now(datetime.UTC) - last_date).days

        if days_since <= 30:
            score += 25  # Very active
        elif days_since <= 90:
            score += 15  # Moderately active
        elif days_since <= 365:
            score += 5   # Slow but still maintained
            warnings.append(f"No published update in {days_since} days")
        else:
            issues.append(f"Package appears abandoned ({days_since} days since last publish)")

    # Check download trend (last 4 weeks vs previous 4 weeks)
    downloads_current = registry_data.get("downloads_last_4weeks", 0)
    downloads_previous = registry_data.get("downloads_previous_4weeks", 0)

    if downloads_previous > 0:
        growth_rate = (downloads_current - downloads_previous) / downloads_previous
        if growth_rate >= 0.10:
            score += 25  # Growing ecosystem
        elif growth_rate >= 0.0:
            score += 15  # Stable
        elif growth_rate >= -0.20:
            score += 5   # Declining slowly
            warnings.append(f"Download volume declining {abs(growth_rate * 100):.0f}%")
        else:
            issues.append(f"Ecosystem declining rapidly ({abs(growth_rate * 100):.0f}% drop)")

    if github_data:
        # Check contributor diversity (bus factor proxy)
        contributors = github_data.get("total_contributors", 0)
        recent_commits_90d = github_data.get("commits_last_90_days", 0)

        if contributors >= 10:
            score += 25  # Healthy contributor base
        elif contributors >= 3:
            score += 15  # Moderate
            warnings.append(f"Only {contributors} contributors — bus factor risk")
        else:
            issues.append(f"Single-maintainer risk with only {contributors} contributors")

        if recent_commits_90d > 20:
            score += 25
        elif recent_commits_90d > 5:
            score += 15
        else:
            warnings.append(f"Low commit activity: {recent_commits_90d} commits in 90 days")

    return {
        "package": package_name,
        "health_score": min(100, score),
        "issues": issues,
        "warnings": warnings,
        "verdict": (
            "ADOPT" if not issues and len(warnings) <= 1 else
            "ADOPT_WITH_CAUTION" if not issues else
            "HIGH_RISK"
        ),
    }
```

---

## Constraints

### MUST DO
- Ground every technology recommendation in measurable requirements, never in popularity or trend analysis alone
- Require at least one production reference in the relevant domain before recommending a technology
- Always include adoption risk scoring alongside fit scoring — a perfect-fit technology with high adoption risk can sink a project
- Plan rollback criteria before beginning any technology adoption process
- Document rejected alternatives with explicit reasoning, not just "we chose X"
- Verify team learning bandwidth matches the technology's complexity before recommending it
- Start with the framework's core patterns before exploring advanced or experimental features

### MUST NOT DO
- Do not recommend a technology without checking its last 6 months of release history and activity
- Do not skip the phased rollout planning — "big bang" migrations are the single most common cause of technology adoption failures
- Do not ignore operational complexity (monitoring, debugging, deployment) in your evaluation
- Do not let a team member's personal preference override evidence from the decision matrix
- Do not adopt bleeding-edge technology (less than 6 months since first stable release) for production systems without explicit executive risk acceptance
- Do not evaluate technologies using only vendor-published information — always cross-reference with independent sources

---

## Output Template

When this skill is active, produce:

1. **Requirements Summary** — Numbered list of concrete, measurable requirements with weights summing to 1.0
2. **Capability Mapping** — Table mapping each requirement to specific technical capabilities the technology must provide
3. **Decision Matrix** — Ranked candidates with fit scores, adoption risk levels, and capability breakdowns
4. **Production References** — Evidence for top candidate's production viability in your domain (case studies, benchmarks, community projects)
5. **Rollout Plan** — Phased milestones with specific exit criteria and rollback actions
6. **Core Patterns Guide** — The 3-5 patterns that unlock most of the technology's value, with brief implementation guidance

---

## Related Skills

| Skill | Purpose |
|---|---|
| `framework-selection` | Structured weighted scoring methodology used within this skill's decision matrix step |
| `framework-utilization` | Integration patterns for leveraging a selected framework's capabilities in your codebase |
| `software-architecture` | Evaluates architectural patterns that influence which technologies fit the overall system design |
| `hexagonal-architecture` | Designs abstraction layers around adopted technologies to minimize coupling and future migration costs |

---

## Live References

> Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

- [Wikipedia — Technology Adoption Lifecycle](https://en.wikipedia.org/wiki/Technology_adoption_lifecycle)
- [Gartner — IT Research & Technology Adoption Insights](https://www.gartner.com/en/information-technology)
- [Marc Andreessen — Why Software Is Eating the World](https://techcrunch.com/2011/08/19/why-software-is-eating-the-world/)
- [Harvard Business Review — Technology Adoption Strategies for Enterprise](https://hbr.org/search?q=technology+adoption)
- [Standish Group — CHAOS Report on Technology Project Success Rates](https://standishgroup.com/sample_research_project/)

## Example: Complete Technology Decision

### Project Context

Building a customer-facing API service requiring 5,000 requests/second with <100ms P95 latency. Team of 5 engineers with strong Python experience (Django production history), no Go or Rust background. Budget for managed services is limited. Must ship first version in 8 weeks.

### Defined Requirements

| Requirement | Weight | Measurable Definition |
|---|---|---|
| Performance throughput | 0.25 | Sustained 5,000 req/s with P95 < 100ms on single container |
| Team velocity | 0.20 | Feature development rate matches or exceeds Django baseline |
| Time to production MVP | 0.15 | Working API deployable within 8 weeks from project kickoff |
| Operational simplicity | 0.15 | Can be monitored with basic HTTP metrics and structured logging |
| Ecosystem for domain needs | 0.10 | Rich set of validation, serialization, and authentication packages |

### Candidates Evaluated

```python
# Example evaluation results from TechnologyDecisionEngine
candidates = [
    {
        "candidate": "FastAPI",
        "version": "0.115+",
        "weighted_fit": 8.4,
        "adoption_risk": "LOW",
        "adoption_risk_score": 4.25,
        "capability_breakdown": {
            "Performance throughput": 9,
            "Team velocity": 7,
            "Time to production MVP": 9,
            "Operational simplicity": 8,
            "Ecosystem for domain needs": 7,
        },
    },
    {
        "candidate": "Django REST Framework",
        "version": "4.3+",
        "weighted_fit": 7.1,
        "adoption_risk": "LOW",
        "adoption_risk_score": 4.50,
        "capability_breakdown": {
            "Performance throughput": 6,
            "Team velocity": 9,
            "Time to production MVP": 8,
            "Operational simplicity": 9,
            "Ecosystem for domain needs": 9,
        },
    },
    {
        "candidate": "Go + Gin",
        "version": "1.23+",
        "weighted_fit": 7.8,
        "adoption_risk": "ELEVATED",
        "adoption_risk_score": 2.75,
        "capability_breakdown": {
            "Performance throughput": 10,
            "Team velocity": 4,
            "Time to production MVP": 5,
            "Operational simplicity": 8,
            "Ecosystem for domain needs": 6,
        },
    },
]

# Ranked by fit score, then risk level:
ranked = TechnologyDecisionEngine.rank_candidates(candidates)
# Result: FastAPI (8.4) > Go/Gin (7.8) > Django REST (7.1)
```

### Production References for FastAPI

- **Starlette** (FastAPI's ASGI foundation): Used by OpenAI, Netflix, and Microsoft Azure SDKs in production
- **Pydantic v2**: Adopted by AWS Lambda Powertools, Palo Alto Networks, and Shopify for high-performance serialization
- Real-world case study: DigitalOcean migrated from Flask to FastAPI, achieving 10x throughput improvement (published blog post, 2024)
- GitHub search: 4,200+ active repositories using FastAPI with commits in the last 90 days

### Rollout Plan

```python
rollout = plan_adoption_rollout(
    project_name="Customer API Service",
    technology_name="FastAPI",
    team_size=5,
    criticality="medium",
)

# Output:
# Phase 1: Technical Spike (7 days)
#   - Exit: Core performance challenge resolved with documented code
#   - Rollback: Revert to Django REST; archive spike artifacts

# Phase 2: Prototype (14 days)
#   - Exit: Full CI/CD pipeline + <1% error rate in prototype
#   - Rollback: Post-mortem on adoption blockers

# Phase 3: Limited Pilot (30 days)
#   - Exit: <0.5% error rate, <4hr bug fix time, 80% team satisfaction
#   - Rollback: Revert pilot feature; document specific issues
```

### Core Patterns to Learn First

1. **Pydantic models for request/response validation** — eliminates boilerplate serialization code and provides automatic OpenAPI documentation
2. **Dependency injection with `Depends()`** — FastAPI's built-in DI system handles auth, database sessions, and configuration cleanly
3. **Background tasks and async handlers** — non-blocking operations for I/O-bound work (API calls, queue processing)
4. **Structured logging middleware** — integrate `structlog` or equivalent for production-grade observability

Avoid premature investment in: advanced WebSocket patterns, custom middleware chains, or the full plugin system — these add complexity without proportional value in a standard API service.