Framework Lifecycle

Framework Decision Lifecycle

When this skill is active, you act as a technology governance orchestrator that guides teams through the complete lifecycle of framework and technology decisions — from initial requirements elicitation through evaluation, selection, integration, and ongoing re-evaluation. You ensure every phase-gate decision is evidence-based, documented, and reversible before production commitment.

TL;DR Checklist

• Elicit and categorize requirements using MoSCoW priority (Must, Should, Could, Won't)
• Build a weighted evaluation matrix where weights sum to exactly 1.0
• Research at least 2 viable candidates using GitHub metrics, ecosystem analysis, and community benchmarks
• Score all candidates against every criterion with evidence citations — never subjective ratings alone
• Run a formal gate decision: green (proceed), conditional (approve with specified conditions), or red (re-evaluate)
• Build a validation spike exercising critical paths before final commitment
• Establish a re-evaluation cadence with specific triggers tied to version events, security incidents, and team growth

When to Use

Use this skill when:

• A team is selecting a new framework for a major component or greenfield project (e.g., choosing between React, Angular, Svelte for a web frontend)
• An existing framework decision needs formal re-evaluation due to deprecation events, security incidents, or significant performance regressions
• A technology committee or architecture review board requires structured evidence for a framework selection decision
• You need to plan a framework migration or rollback strategy before committing to an irreversible integration approach
• The team is growing beyond initial founding members and needs governance over technology choices to prevent drift
• Evaluating whether to adopt a newer framework vs. stick with a mature, stable one (e.g., Laravel 10 vs. Livewire 3)

When NOT to Use

Avoid this skill for:

• Trivial component-level decisions where the cost of switching is negligible (use quick heuristic instead)
• Situations where leadership has already made a binding directive and no evidence gathering is needed
• Micro-framework or library picks that do not shape architectural boundaries (e.g., choosing between uuid libraries)
• Emergency hotfixes where speed overrides governance — apply the fix first, document retroactively

Core Workflow

1. Elicit Requirements

Conduct structured requirements elicitation across four categories. Do not accept vague requests like "we need a modern framework." Drill down with specific questions.

Functional Requirements — What must the framework do?

• Routing model (REST, GraphQL, RPC, server-sent events)
• Template rendering or component composition approach
• Built-in ORM/data access layer requirements
• Authentication/authorization integration patterns
• Real-time capability (WebSockets, SSE, polling)

Non-Functional Requirements — Quality attributes the framework must support.

• Performance targets: response time < 200ms p95, throughput > 1000 req/s
• Bundle size budgets: initial load < 200KB gzipped
• Accessibility compliance: WCAG 2.1 AA minimum
• SEO requirements: SSR/SSG necessity

Operational Requirements — How the framework interacts with operational concerns.

• CI/CD pipeline compatibility (build times, test execution)
• Monitoring and observability integration hooks
• Logging standardization (structured JSON logging)
• Containerization support (multi-stage build optimization)

Compliance Requirements — Regulatory or organizational mandates.

• License compatibility (GPL vs MIT vs Apache 2.0)
• Data sovereignty requirements
• Audit trail capabilities
• SOC2/HIPAA compliance considerations

Checkpoint: Before proceeding, classify all gathered requirements by MoSCoW priority. At least 3 Must-have requirements must be identified. Requirements with only "Could" or "Won't" priority must be moved to a backlog and excluded from the evaluation matrix weights.

2. Define Evaluation Criteria

Translate each Must and Should requirement into measurable criteria with assigned weight scores. The total of all criterion weights must equal exactly 1.0.

Criteria Design Process:

For each MoSCoW "Must" requirement: weight = 0.10–0.20
For each MoSCoW "Should" requirement: weight = 0.03–0.08
For cross-cutting concerns (licensing, community): weight = 0.05–0.10 total

Weight Validation Rule: The sum of all weights must be exactly 1.0 (±0.001 tolerance). If not, normalize by dividing each weight by the total sum.

Measurability Test: For every criterion, ask: "Can I score a framework on this using evidence from documentation, benchmarks, or third-party assessments?" If the answer is no, the criterion must be reformulated with concrete measurement methods.

Checkpoint: Verify all weights sum to 1.0 and each criterion has an associated evidence source (GitHub stars, npm download trends, OWASP compliance report, Stack Overflow question volume).

3. Identify Candidate Frameworks

Research frameworks using a structured discovery process. Do not rely on personal preference or recency bias — use quantifiable signals.

Research Methods:

1. GitHub Metrics Analysis (for open-source frameworks)

   • Star count growth rate over 12 months (not absolute stars)
   • Issue resolution median time (from GitHub API get_issues)
   • Release cadence consistency (months between minor releases)
   • Contributor diversity: percentage of contributors with >1 commit in last year

2. Ecosystem Analysis

   • Available middleware/plugins count and maintenance status
   • First-party documentation quality score (completeness + examples)
   • Third-party library compatibility matrix
   • Tooling ecosystem (CLI tools, IDE extensions, debugging support)

3. Benchmark Review

   • Standardized performance benchmarks (e.g., Web Framework Benchmark for web frameworks)
   • Memory footprint under load (from published benchmarks or independent testing)
   • Build time comparison across comparable project sizes
   • Bundle size analysis using tools like webpack-bundle-analyzer

4. Community Assessment

   • Stack Overflow question volume and answer rate over 6 months
   • Number of production case studies available (not blog posts, but deployed systems)
   • Conference presence (number of talks per year at major conferences)
   • Commercial support availability and vendor stability

Checkpoint: At minimum 2 viable candidates must be identified. If fewer than 2 pass the screening criteria (Meets all "Must" requirements), expand research scope or re-evaluate Must requirements — do not proceed with a single untested candidate.

4. Execute Evaluation Matrix

Score each candidate against every weighted criterion using evidence-based scoring. Never score based on opinion alone.

Scoring Scale:

Evidence-Based Scoring Rules:

• Every score must cite at least one evidence source (URL, benchmark number, documentation reference)
• Scores below 3 on any "Must" criterion requirement trigger automatic disqualification of that candidate for that criterion
• Cross-validate scores: if two team members score independently, they must agree within ±1 point. Discrepancies require a joint review session.

Weighted Score Calculation: final_score = sum(criterion_weight × score) across all criteria. Rank candidates by final weighted score.

Checkpoint: All candidates must have complete evidence for every scored criterion. Partial scores without evidence are invalid. If any criterion is missing evidence, return to that candidate and fill the gap before proceeding.

5. Gate Decision Review

Conduct a formal gate review with all stakeholders present. Present the evaluation matrix, evidence citations, spike results (if available), and risk assessment. The decision must be one of three outcomes:

Green Light: Proceed to integration planning immediately.

• All "Must" criteria satisfied across top-ranked candidates
• No critical risks identified
• Spike validation passed all success criteria
• Next action: move to Step 6 (Integration Strategy) within 1 sprint

Conditional Approval: Proceed with specific conditions that must be met before production.

• Document each condition as a concrete acceptance criterion
• Example conditions: "Complete security audit of authentication middleware before v1 launch", "Resolve performance regression on list view (>500 items)", "Migrate from beta API to stable API before feature freeze"
• Set deadlines for each condition (specific dates, not "soon")
• Assign owners for each condition
• If conditions are not met by deadline, decision escalates to Red Light

Red Light: Do NOT proceed. Return to an earlier step.

• Re-evaluate requirements (Step 1) if critical criteria were misunderstood
• Expand candidate search (Step 3) if current candidates lack sufficient evidence
• Consider alternative architectures if no framework meets core requirements
• Document the decision and reasons in an Architecture Decision Record (ADR)

Checkpoint: The gate decision outcome must be documented with explicit reasoning, stakeholder signatures, and recorded dissenting opinions. No unrecorded verbal approvals are valid.

6. Plan Integration Strategy

Design the integration approach based on the selected framework's specific characteristics. This is not generic — tailor every aspect to the chosen framework.

DI Topology Design:

• Map all application services to their DI lifetimes (singleton, scoped, transient)
• Define the composition root location and module boundaries
• Identify circular dependency risks and plan resolution strategies (interface segregation, event-based decoupling)

Configuration Strategy:

• Environment-specific configuration files (dev, staging, production)
• Secrets management integration (Vault, AWS Secrets Manager, or equivalent)
• Configuration validation at startup (schema validation, required field checks)
• Hot-reload capability for non-sensitive configuration during development

Extension Point Design:

• Define plugin/interceptor/middleware boundaries based on framework patterns
• Document the expected contract for each extension point (interfaces, type signatures)
• Plan for third-party extension compatibility testing

Testing Approach:

• Unit test strategy: percentage of critical path coverage target (>80%)
• Integration test scope: which external dependencies are mocked vs. tested live
• E2E test selection criteria: user journeys that represent >90% of business value
• Performance test automation in CI pipeline

Checkpoint: Complete a coupling analysis — for each integration point, classify coupling as tight (direct class/func dependency), medium (interface-based dependency), or loose (event/message-based). Target at least 60% loose or medium coupling. Tight coupling must be justified with specific constraints (performance-critical path, framework-mandated pattern).

7. Build Validation Spike

Construct a minimal proof-of-concept that exercises the critical integration paths identified in the evaluation matrix. The spike must not be production-ready — it is designed to fail fast and reveal hidden costs.

Minimum Spike Requirements:

• Implement at least one end-to-end user journey (not just a single component)
• Exercise the framework's routing or request handling mechanism
• Demonstrate data persistence through the framework's recommended ORM/driver
• Show configuration loading from at least two different environment profiles
• Include error handling and graceful degradation for the primary failure mode

Performance Thresholds to Test:

• Initial render/load time under simulated 3G network conditions (Lighthouse or equivalent)
• API response time p95 under load of 100 concurrent requests
• Memory usage stability over a 30-minute sustained request period
• Build/compile time for the spike project vs. projected production impact

Failure Modes to Validate:

• Connection failure to database/backend service — does it degrade gracefully?
• Authentication token expiration — is refresh handled without user disruption?
• Invalid input data — does the framework validate and return appropriate errors?
• High load condition — identify the breaking point before it occurs in production

Checkpoint: Define explicit spike success criteria before starting. Example: "Spike passes if all four performance thresholds are met, error handling covers three failure modes with <50ms overhead, and the total spike build time is under 2 hours." If the spike fails to meet any critical threshold, escalate to Red Light decision or return to Step 3 with revised candidate list.

8. Establish Re-evaluation Cadence

Define when and how the framework choice will be re-evaluated over its operational lifetime. This step prevents technology debt accumulation through neglect.

Re-evaluation Triggers (Concrete Events):

1. Version Deprecation Events: Framework maintainer announces end-of-life, security-only updates, or major version migration away from LTS. Action: initiate formal re-evaluation within 30 days of announcement.

2. Security Incidents: CVE with CVSS ≥ 7.0 affects the framework or its core dependencies. Action: assess mitigation viability; if unfixable in current version, trigger emergency evaluation of alternative.

3. Performance Regressions: Measured application performance degrades by >15% compared to baseline (established at integration time), after ruling out infrastructure and data growth causes. Action: investigate whether framework upgrade resolves regression or signals need for migration.

4. Team Growth Milestones: Team size exceeds the number of documented "framework champions" (people with deep expertise). When team grows >3×, re-evaluate if onboarding complexity justifies alternative. Threshold: new hires must reach productive velocity within 2 sprints.

5. Ecosystem Shifts: A competing framework achieves a critical mass shift (e.g., overtaking current framework in GitHub star growth rate × 6 months, or major enterprise adoption). Action: assess whether the ecosystem shift impacts long-term talent availability and library support.

Re-evaluation Documentation Requirements:

• Record the re-evaluation schedule (quarterly for new frameworks, bi-annually for mature ones)
• Define who owns the re-evaluation decision (tech lead, architecture board, individual contributor?)
• Create a rollback readiness checklist that is reviewed at each re-evaluation cycle
• Store re-evaluation results in the same location as the original ADR

Checkpoint: Document the full re-evaluation plan with specific trigger conditions, responsible persons, and escalation paths. Verify the plan covers at least 3 of the 5 trigger types listed above.

Implementation Patterns / Reference Guide

Pattern 1: Phase-Gate Decision Matrix

A state machine that manages phase-gate decisions for the framework lifecycle, enforcing validation rules at each transition.

from enum import Enum
from typing import Optional
from dataclasses import dataclass, field


class GateOutcome(Enum):
    """Formal gate decision outcomes."""
    GREEN = "green_light"
    CONDITIONAL = "conditional_approval"
    RED = "red_light"


class LifecycleState(Enum):
    """Phases in the framework decision lifecycle."""
    REQUIREMENTS_DEFINED = "requirements-defined"
    EVALUATION_COMPLETE = "evaluation-complete"
    GATE_DECISION = "gate-decision"
    SPIKE_VALIDATED = "spike-validated"
    PRODUCTION_INTEGRATED = "production-integrated"


@dataclass
class GateCondition:
    """A condition attached to conditional approval."""
    description: str
    acceptance_criteria: str
    deadline_iso: str
    owner: str


@dataclass
class PhaseGateMatrix:
    """Manages phase-gate decisions for the framework decision lifecycle.

    Enforces ordered state transitions, validates prerequisite data at each gate,
    and tracks conditional approval conditions that must be satisfied before
    proceeding to production integration.

    Usage:
        matrix = PhaseGateMatrix("frontend-ui-replacement")
        matrix.advance_to(LifecycleState.EVALUATION_COMPLETE,
                          weighted_scores={"security": 0.15, "performance": 0.20})
        result = matrix.evaluate_gate()
        if result.outcome is GateOutcome.GREEN:
            matrix.advance_to(LifecycleState.SPIKE_VALIDATED)
    """

    framework_id: str
    current_state: LifecycleState = LifecycleState.REQUIREMENTS_DEFINED
    evaluation_criteria: dict[str, float] = field(default_factory=dict)
    candidate_scores: dict[str, dict[str, float]] = field(default_factory=dict)
    gate_conditions: list[GateCondition] = field(default_factory=list)
    gate_history: list[dict] = field(default_factory=list)
    transition_log: list[dict] = field(default_factory=list)

    # Allowed state transitions: from -> set of allowed "to" states
    _ALLOWED_TRANSITIONS: dict[LifecycleState, set[LifecycleState]] = {
        LifecycleState.REQUIREMENTS_DEFINED: {LifecycleState.EVALUATION_COMPLETE},
        LifecycleState.EVALUATION_COMPLETE: {LifecycleState.GATE_DECISION},
        LifecycleState.GATE_DECISION: {
            LifecycleState.EVALUATION_COMPLETE,  # conditional or red -> retry
            LifecycleState.SPIKE_VALIDATED,       # green light
        },
        LifecycleState.SPIKE_VALIDATED: {LifecycleState.PRODUCTION_INTEGRATED},
    }

    def advance_to(self, target_state: LifecycleState,
                   weighted_scores: Optional[dict[str, float]] = None) -> dict:
        """Transition to a new lifecycle state with validation.

        Args:
            target_state: The state to transition into.
            weighted_scores: Evaluation criteria weights (must sum to 1.0).

        Returns:
            Transition result with success/failure status and reason.

        Raises:
            ValueError: If the transition is invalid or prerequisites are unmet.
        """
        allowed = self._ALLOWED_TRANSITIONS.get(self.current_state, set())

        if target_state not in allowed:
            raise ValueError(
                f"Cannot transition from {self.current_state.value} to "
                f"{target_state.value}. Allowed: {[s.value for s in allowed]}"
            )

        # Prerequisite validation per state
        if target_state is LifecycleState.EVALUATION_COMPLETE:
            if not weighted_scores or abs(sum(weighted_scores.values()) - 1.0) > 0.001:
                raise ValueError("Evaluation criteria weights must sum to exactly 1.0")
            self.evaluation_criteria = weighted_scores

        if target_state is LifecycleState.GATE_DECISION:
            if not self.evaluation_criteria:
                raise ValueError("Cannot evaluate gate without defined criteria")
            if not self.candidate_scores:
                raise ValueError("Cannot evaluate gate without candidate scores")

        previous_state = self.current_state
        self.current_state = target_state
        self.transition_log.append({
            "from": previous_state.value,
            "to": target_state.value,
            "timestamp": None,  # set by caller if needed
        })

        return {
            "success": True,
            "previous_state": previous_state.value,
            "current_state": target_state.value,
        }

    def evaluate_gate(self) -> dict:
        """Evaluate the current gate decision based on candidate scores.

        Returns a GateOutcome (GREEN, CONDITIONAL, or RED) with supporting details.

        GREEN: Top candidate has weighted score >= 70 and no Must-criterion failures.
        CONDITIONAL: Top candidate meets threshold but has noted risks.
        RED: No candidate passes threshold or critical criteria are unmet.
        """
        if not self.candidate_scores or not self.evaluation_criteria:
            return {"outcome": GateOutcome.RED.value, "reason": "Missing evaluation data"}

        # Calculate weighted scores for each candidate
        scored_candidates = {}
        for candidate, scores in self.candidate_scores.items():
            total = 0.0
            must_failures = []
            risks = []
            for criterion, weight in self.evaluation_criteria.items():
                score = scores.get(criterion, 1)
                weighted = weight * score
                total += weighted
                if weight >= 0.10 and score < 3:
                    must_failures.append(criterion)
                elif score <= 2:
                    risks.append(f"{criterion} scored {score}")

            scored_candidates[candidate] = {
                "weighted_score": total,
                "must_failures": must_failures,
                "risks": risks,
            }

        # Determine outcome based on top candidate
        best = max(scored_candidates.items(), key=lambda x: x[1]["weighted_score"])
        best_candidate, details = best

        if details["must_failures"] or details["weighted_score"] < 60:
            result = GateOutcome.RED
            reason = (f"{best_candidate}: weighted score {details['weighted_score']:.2f}, "
                      f"Must-failures: {', '.join(details['must_failures'])}")
        elif details["risks"]:
            result = GateOutcome.CONDITIONAL
            self.gate_conditions.append(GateCondition(
                description=f"Address risks for {best_candidate}",
                acceptance_criteria="Resolve all identified risk items",
                deadline_iso="",  # set by decision owner
                owner="",
            ))
            reason = (f"{best_candidate}: score {details['weighted_score']:.2f}, "
                      f"risks: {', '.join(details['risks'])}")
        else:
            result = GateOutcome.GREEN
            reason = f"{best_candidate} scored {details['weighted_score']:.2f} with no critical risks"

        self.gate_history.append({
            "outcome": result.value,
            "reason": reason,
            "top_candidate": best_candidate,
            "scores": {k: v["weighted_score"] for k, v in scored_candidates.items()},
        })

        return {
            "outcome": result.value,
            "reason": reason,
            "candidates": {k: v["weighted_score"] for k, v in scored_candidates.items()},
            "conditions_count": len(self.gate_conditions),
        }

    def register_candidate_scores(self, candidate_name: str,
                                  scores: dict[str, float]) -> None:
        """Register evidence-based scores for a candidate framework.

        Args:
            candidate_name: Identifier for the candidate framework.
            scores: Mapping of criterion names to scores (1-5 scale).
        """
        self.candidate_scores[candidate_name] = scores

    def mark_conditions_met(self, condition_index: int) -> bool:
        """Mark a gate condition as satisfied."""
        if 0 <= condition_index < len(self.gate_conditions):
            self.gate_conditions.pop(condition_index)
            return True
        return False

Pattern 2: Re-evaluation Trigger Engine

Monitors and evaluates re-evaluation triggers against a framework instance over time. Each trigger type has specific evaluation logic with concrete thresholds.

import asyncio
from datetime import datetime, timedelta
from dataclasses import dataclass, field
from enum import Enum
from typing import Optional


class TriggerType(Enum):
    """Types of re-evaluation triggers."""
    SECURITY = "security"
    PERFORMANCE = "performance"
    ECOSYSTEM = "ecosystem"
    TEAM = "team"
    BUSINESS = "business"


@dataclass
class FrameworkInstance:
    """Represents a deployed framework instance with its operational state."""
    name: str
    version: str
    integrated_date: datetime
    baseline_performance_ms: float  # p95 response time at integration
    team_size: int
    ecosystem_github_stars_current: int
    ecosystem_github_stars_at_integration: int
    recent_cves: list[dict] = field(default_factory=list)  # [{"cve_id": "...", "cvss": 8.5, "date": "..."}]
    benchmark_history: list[float] = field(default_factory=list)  # [p95_ms, ...] over time


@dataclass
class TriggerResult:
    """Result of evaluating a single re-evaluation trigger."""
    trigger_type: TriggerType
    severity: str  # "critical", "high", "medium", "low", "none"
    recommendation: str  # "re_evaluate_immediately", "investigate", "monitor", "no_action"
    details: str
    triggered_at: datetime = field(default_factory=datetime.utcnow)


class ReevaluationTriggerEngine:
    """Evaluates re-evaluation triggers against a framework instance.

    Monitors for security incidents, performance regressions, ecosystem shifts,
    team growth, and business changes that warrant re-evaluating the framework choice.

    Evaluation logic uses concrete thresholds rather than subjective judgment.
    Each trigger type has domain-specific metrics and decision boundaries.
    """

    # Threshold constants — these should be tuned per organization
    THRESHOLDS = {
        "security_cvss_critical": 9.0,
        "security_cvss_high": 7.0,
        "performance_regression_pct": 15.0,
        "ecosystem_growth_acceleration_factor": 2.0,
        "team_growth_multiplier": 3.0,
        "benchmark_sample_size": 3,  # min samples for regression detection
    }

    def __init__(self, framework: FrameworkInstance) -> None:
        self.framework = framework
        self.trigger_results: list[TriggerResult] = []

    def evaluate_all(self) -> list[TriggerResult]:
        """Run all trigger evaluations and return results sorted by severity."""
        results = [
            self._evaluate_security(),
            self._evaluate_performance(),
            self._evaluate_ecosystem(),
            self._evaluate_team(),
            self._evaluate_business(),
        ]
        # Sort: critical > high > medium > low > none
        severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3, "none": 4}
        results.sort(key=lambda r: severity_order.get(r.severity, 5))
        self.trigger_results.extend(results)
        return results

    def _evaluate_security(self) -> TriggerResult:
        """Check for security-related CVEs that require immediate action.

        Logic: Any CVSS >= critical_threshold triggers re-evaluation.
               Any CVSS >= high_threshold requires investigation within 7 days.
        """
        critical_cves = [c for c in self.framework.recent_cves
                         if c["cvss"] >= self.THRESHOLDS["security_cvss_critical"]]
        high_cves = [c for c in self.framework.recent_cves
                     if self.THRESHOLDS["security_cvss_high"] <= c["cvss"] <
                        self.THRESHOLDS["security_cvss_critical"]]

        if critical_cves:
            return TriggerResult(
                trigger_type=TriggerType.SECURITY,
                severity="critical",
                recommendation="re_evaluate_immediately",
                details=(f"{len(critical_cves)} CVE(s) with CVSS >= 9.0 detected: "
                         f"{', '.join(c['cve_id'] for c in critical_cves)}. "
                         f"Mitigation may require framework migration or vendor patch."),
            )

        if high_cves:
            return TriggerResult(
                trigger_type=TriggerType.SECURITY,
                severity="high",
                recommendation="investigate",
                details=(f"{len(high_cves)} CVE(s) with CVSS >= 7.0 detected: "
                         f"{', '.join(c['cve_id'] for c in high_cves)}. "
                         f"Investigate mitigation viability within 7 days."),
            )

        return TriggerResult(
            trigger_type=TriggerType.SECURITY,
            severity="none",
            recommendation="no_action",
            details="No critical or high-severity CVEs detected.",
        )

    def _evaluate_performance(self) -> TriggerResult:
        """Detect performance regressions compared to integration baseline.

        Logic: If current p95 response time exceeds baseline by >= 15% AND
               we have at least `benchmark_sample_size` measurements, flag regression.
        """
        if (not self.framework.benchmark_history or
                len(self.framework.benchmark_history) < self.THRESHOLDS["benchmark_sample_size"]):
            return TriggerResult(
                trigger_type=TriggerType.PERFORMANCE,
                severity="none",
                recommendation="no_action",
                details=(f"Insufficient benchmark data: {len(self.framework.benchmark_history)} "
                         f"samples recorded (minimum {self.THRESHOLDS['benchmark_sample_size']} required)."),
            )

        current_p95 = self.framework.benchmark_history[-1]
        regression_pct = ((current_p95 - self.framework.baseline_performance_ms) /
                          self.framework.baseline_performance_ms) * 100

        if regression_pct >= self.THRESHOLDS["performance_regression_pct"]:
            return TriggerResult(
                trigger_type=TriggerType.PERFORMANCE,
                severity="high" if regression_pct >= 30 else "medium",
                recommendation="investigate",
                details=(f"Performance regression detected: current p95 is "
                         f"{current_p95:.0f}ms vs baseline {self.framework.baseline_performance_ms:.0f}ms "
                         f"({regression_pct:.1f}% degradation). Investigate whether a framework "
                         f"upgrade resolves this or if migration is warranted."),
            )

        return TriggerResult(
            trigger_type=TriggerType.PERFORMANCE,
            severity="none",
            recommendation="no_action",
            details=f"Performance within tolerance: {current_p95:.0f}ms vs baseline {self.framework.baseline_performance_ms:.0f}ms ({regression_pct:.1f}% change).",
        )

    def _evaluate_ecosystem(self) -> TriggerResult:
        """Assess ecosystem momentum shifts relative to integration time.

        Logic: If star growth rate has accelerated >= 2× compared to integration period,
               the ecosystem may be shifting away from this framework.
        """
        days_since_integration = (datetime.utcnow() - self.framework.integrated_date).days
        if days_since_integration < 30:
            return TriggerResult(
                trigger_type=TriggerType.ECOSYSTEM,
                severity="none",
                recommendation="no_action",
                details=f"Framework integrated only {days_since_integration} days ago. Waiting for cooldown period.",
            )

        growth_since_integration = (self.framework.ecosystem_github_stars_current -
                                    self.framework.ecosystem_github_stars_at_integration)

        if self.framework.ecosystem_github_stars_at_integration <= 0:
            return TriggerResult(
                trigger_type=TriggerType.ECOSYSTEM,
                severity="none",
                recommendation="no_action",
                details="Baseline star count is zero; ecosystem shift cannot be measured.",
            )

        growth_factor = growth_since_integration / self.framework.ecosystem_github_stars_at_integration
        # Normalize: growth_factor represents total growth since integration
        # We check if current momentum exceeds typical lifecycle pace

        if growth_factor >= self.THRESHOLDS["ecosystem_growth_acceleration_factor"]:
            return TriggerResult(
                trigger_type=TriggerType.ECOSYSTEM,
                severity="medium",
                recommendation="monitor",
                details=(f"Ecosystem growth factor is {growth_factor:.1f}x since integration "
                         f"({self.framework.ecosystem_github_stars_at_integration} → "
                         f"{self.framework.ecosystem_github_stars_current} stars). Monitor for "
                         f"sustained momentum that may indicate market shift."),
            )

        return TriggerResult(
            trigger_type=TriggerType.ECOSYSTEM,
            severity="none",
            recommendation="no_action",
            details=f"Ecosystem growth factor is {growth_factor:.2f}x (below {self.THRESHOLDS['ecosystem_growth_acceleration_factor']}x threshold).",
        )

    def _evaluate_team(self) -> TriggerResult:
        """Check if team growth exceeds framework champion coverage.

        Logic: When team size > 3× original champions, onboarding complexity
               may justify evaluating simpler or better-documented alternatives.
        """
        estimated_champions = max(1, len(self.framework.benchmark_history) // 50)  # rough estimate
        growth_multiplier = self.framework.team_size / estimated_champions

        if growth_multiplier >= self.THRESHOLDS["team_growth_multiplier"]:
            return TriggerResult(
                trigger_type=TriggerType.TEAM,
                severity="medium",
                recommendation="investigate",
                details=(f"Team has grown to {self.framework.team_size} members. "
                         f"Estimated champion coverage ratio is {growth_multiplier:.1f}x. "
                         f"Assess whether onboarding complexity and knowledge concentration "
                         f"justify evaluating alternatives with lower learning curves."),
            )

        return TriggerResult(
            trigger_type=TriggerType.TEAM,
            severity="none",
            recommendation="no_action",
            details=f"Team size ({self.framework.team_size}) is within champion coverage capacity.",
        )

    def _evaluate_business(self) -> TriggerResult:
        """Business-driven trigger: placeholder for business logic changes.

        This evaluates whether business requirements have shifted in ways that
        make the current framework choice suboptimal (e.g., shift from SPA to
        SSR, new regulatory requirements, target market changes).

        To activate this trigger, set `business_revenue_change_pct` on the framework instance.
        """
        return TriggerResult(
            trigger_type=TriggerType.BUSINESS,
            severity="none",
            recommendation="no_action",
            details="No business-change triggers configured. Add domain-specific logic as needed.",
        )

    def has_critical_trigger(self) -> bool:
        """Return True if any triggered result requires immediate action."""
        return any(r.severity in ("critical", "high") for r in self.trigger_results)

    def get_action_summary(self) -> str:
        """Get a human-readable summary of all trigger results."""
        active = [r for r in self.trigger_results if r.severity != "none"]
        if not active:
            return "No re-evaluation triggers active. Framework is stable."

        lines = [f"Re-evaluation triggers detected ({len(active)} active):"]
        for r in active:
            lines.append(f"  [{r.severity.upper()}] {r.trigger_type.value}: {r.recommendation} — {r.details}")
        return "\n".join(lines)

Pattern 3: Framework Technical Debt Ledger

Tracks framework-related technical debt across the lifecycle, including coupling costs, migration complexity estimates, and version upgrade impact assessments.

from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
from typing import Optional


class DebtCategory(Enum):
    """Categories of framework-related technical debt."""
    COUPLING = "coupling"
    MIGRATION_COMPLEXITY = "migration_complexity"
    VERSION_UPGRADE_IMPACT = "version_upgrade_impact"
    DEPENDENCY_DECAY = "dependency_decay"
    LEARNING_CURVE = "learning_curve"


class DebtSeverity(Enum):
    """Severity levels for framework technical debt."""
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"


@dataclass
class LedgerEntry:
    """A single entry in the framework technical debt ledger.

    Represents a specific source of technical debt related to the framework choice,
    with quantified cost estimates and an expected decay/interest rate.
    """
    id: str
    category: DebtCategory
    description: str
    severity: DebtSeverity
    estimated_effort_hours: float  # hours to resolve or mitigate
    annual_interest_hours: float   # hours of friction accumulated per year
    first_reported: datetime
    resolved: bool = False
    resolved_at: Optional[datetime] = None

    @property
    def total_accumulated_hours(self) -> float:
        """Calculate total debt including interest accrued to date."""
        age_years = (datetime.utcnow() - self.first_reported).days / 365.0
        return self.estimated_effort_hours + (self.annual_interest_hours * age_years)


class FrameworkTechnicalDebtLedger:
    """Tracks framework-related technical debt across the lifecycle.

    Maintains a ledger of all identified framework technical debt items,
    calculates accumulated interest over time, and provides analysis on
    migration complexity and upgrade impact.

    This ledger helps answer: "How much is our framework choice costing us per year?"
    and "What would migration cost if triggered by an emergency vs. planned move?"

    Usage:
        ledger = FrameworkTechnicalDebtLedger("react-18-frontend")
        ledger.add_entry(
            category=DebtCategory.COUPLING,
            description="Component tree tightly coupled to framework render lifecycle",
            severity=DebtSeverity.HIGH,
            effort_hours=120,
            annual_interest=40,
        )
        analysis = ledger.analyze_migration_readiness()
    """

    def __init__(self, framework_id: str) -> None:
        self.framework_id = framework_id
        self.entries: list[LedgerEntry] = []
        self._next_id = 0

    def add_entry(self, category: DebtCategory, description: str,
                  severity: DebtSeverity, effort_hours: float,
                  annual_interest_hours: float) -> LedgerEntry:
        """Record a new technical debt item in the ledger.

        Args:
            category: The type of framework-related debt being tracked.
            description: Human-readable explanation of the debt.
            severity: How urgent this debt is to address.
            effort_hours: Estimated hours to resolve the root cause.
            annual_interest_hours: Hours of friction accumulated per year from this debt.

        Returns:
            The created LedgerEntry with assigned ID.
        """
        self._next_id += 1
        entry = LedgerEntry(
            id=f"{self.framework_id}-DEBT-{self._next_id:03d}",
            category=category,
            description=description,
            severity=severity,
            estimated_effort_hours=effort_hours,
            annual_interest_hours=annual_interest_hours,
            first_reported=datetime.utcnow(),
        )
        self.entries.append(entry)
        return entry

    def resolve_entry(self, entry_id: str) -> bool:
        """Mark a ledger entry as resolved at the current time."""
        for entry in self.entries:
          

…(truncated)