tech-stack-evaluator

Technology Stack Evaluator

Evaluate and compare technologies, frameworks, and cloud providers with data-driven analysis and actionable recommendations.

Table of Contents

• [Capabilities](#capabilities)
• [Quick Start](#quick-start)
• [Input Formats](#input-formats)
• [Analysis Types](#analysis-types)
• [Scripts](#scripts)
• [References](#references)

Capabilities

| Capability | Description | |------------|-------------| | Technology Comparison | Compare frameworks and libraries with weighted scoring | | TCO Analysis | Calculate 5-year total cost including hidden costs | | Ecosystem Health | Assess GitHub metrics, npm adoption, community strength | | Security Assessment | Evaluate vulnerabilities and compliance readiness | | Migration Analysis | Estimate effort, risks, and timeline for migrations | | Cloud Comparison | Compare AWS, Azure, GCP for specific workloads |

Quick Start

Compare Two Technologies

Compare React vs Vue for a SaaS dashboard.
Priorities: developer productivity (40%), ecosystem (30%), performance (30%).

Calculate TCO

Calculate 5-year TCO for Next.js on Vercel.
Team: 8 developers. Hosting: $2500/month. Growth: 40%/year.

Assess Migration

Evaluate migrating from Angular.js to React.
Codebase: 50,000 lines, 200 components. Team: 6 developers.

Input Formats

The evaluator accepts three input formats:

Text - Natural language queries

Compare PostgreSQL vs MongoDB for our e-commerce platform.

YAML - Structured input for automation

comparison:
  technologies: ["React", "Vue"]
  use_case: "SaaS dashboard"
  weights:
    ecosystem: 30
    performance: 25
    developer_experience: 45

JSON - Programmatic integration

{
  "technologies": ["React", "Vue"],
  "use_case": "SaaS dashboard"
}

Analysis Types

Quick Comparison (200-300 tokens)

• Weighted scores and recommendation
• Top 3 decision factors
• Confidence level

Standard Analysis (500-800 tokens)

• Comparison matrix
• TCO overview
• Security summary

Full Report (1200-1500 tokens)

• All metrics and calculations
• Migration analysis
• Detailed recommendations

Scripts

stack_comparator.py

Compare technologies with customizable weighted criteria.

python scripts/stack_comparator.py --help

tco_calculator.py

Calculate total cost of ownership over multi-year projections.

python scripts/tco_calculator.py --input assets/sample_input_tco.json

ecosystem_analyzer.py

Analyze ecosystem health from GitHub, npm, and community metrics.

python scripts/ecosystem_analyzer.py --technology react

security_assessor.py

Evaluate security posture and compliance readiness.

python scripts/security_assessor.py --technology express --compliance soc2,gdpr

migration_analyzer.py

Estimate migration complexity, effort, and risks.

python scripts/migration_analyzer.py --from angular-1.x --to react

References

| Document | Content | |----------|---------| | references/metrics.md | Detailed scoring algorithms and calculation formulas | | references/examples.md | Input/output examples for all analysis types | | references/workflows.md | Step-by-step evaluation workflows |

Confidence Levels

| Level | Score | Interpretation | |-------|-------|----------------| | High | 80-100% | Clear winner, strong data | | Medium | 50-79% | Trade-offs present, moderate uncertainty | | Low | < 50% | Close call, limited data |

When to Use

• Comparing frontend/backend frameworks for new projects
• Evaluating cloud providers for specific workloads
• Planning technology migrations with risk assessment
• Calculating build vs. buy decisions with TCO
• Assessing open-source library viability

When NOT to Use

• Trivial decisions between similar tools (use team preference)
• Mandated technology choices (decision already made)
• Emergency production issues (use monitoring tools)

Troubleshooting

| Problem | Cause | Solution | |---------|-------|----------| | Weighted scores all return 50.0 | Technology data dictionaries missing score keys under each category | Ensure each category dict contains a score key on a 0-100 scale (e.g., {"performance": {"score": 85}}) | | TCO projections look unrealistically low | Default cost parameters used when operational_costs or initial_costs are empty | Populate monthly_hosting, annual_licensing, developer_hourly_rate, and maintenance_hours_per_dev_monthly with real figures | | Ecosystem health score stuck at 50 for npm | npm_data dict is empty or not provided | Pass npm metrics (weekly_downloads, version, dependencies_count, days_since_last_publish); 50 is the neutral fallback when npm data is absent | | Security compliance returns "Unknown standard" | Unsupported standard name passed to assess_compliance() | Use one of the supported keys: GDPR, SOC2, HIPAA, PCI_DSS (case-sensitive) | | Migration complexity always shows moderate | architecture_change_level defaults to moderate when not specified | Set architecture_change_level explicitly to minimal, moderate, significant, or complete in codebase_stats | | Report renders ASCII tables instead of markdown | ReportGenerator auto-detects CLI context when stdout is a TTY | Pass output_context='desktop' to force rich markdown output | | Format detector misclassifies YAML as text | Fewer than 50% of lines match YAML key-value patterns | Ensure input uses standard YAML syntax with key: value pairs and proper indentation |

Success Criteria

• TCO variance under 15%: Calculated TCO deviates less than 15% from actual costs when validated against real-world spending data over the projection period.
• Security score above 80/100: Technologies recommended for production use achieve a minimum overall security score of 80, corresponding to grade B or higher.
• Ecosystem health score above 65/100: Recommended technologies demonstrate viable long-term ecosystem health with a risk level no worse than "Low-Medium."
• Migration effort estimate within 20%: Person-hours and timeline estimates land within 20% of actual migration effort when measured post-completion.
• Comparison confidence above 70%: Final technology recommendations carry a confidence score of 70% or higher, indicating a meaningful score gap between top candidates.
• Compliance readiness at "Mostly Ready" or above: Technologies targeting regulated environments achieve at least 70% feature coverage against required compliance standards (GDPR, SOC2, HIPAA, PCI-DSS).
• Report generation under 5 seconds: All report types (executive summary, full report) render within 5 seconds for evaluations comparing up to 5 technologies.

Scope & Limitations

Covers:

• Weighted multi-criteria comparison of frameworks, libraries, and cloud providers
• Multi-year TCO projections including hidden costs (technical debt, vendor lock-in, turnover)
• Ecosystem viability assessment using GitHub, npm, and community metrics
• Security posture scoring and compliance readiness for GDPR, SOC2, HIPAA, PCI-DSS

Does NOT cover:

• Live data fetching from GitHub API, npm registry, or vulnerability databases (all data must be provided as input dictionaries)
• Performance benchmarking or load testing (use engineering/senior-qa for test execution)
• Licensing legal review or contract negotiation (use ra-qm-team compliance skills for regulatory guidance)
• Team hiring or organizational design decisions (use hr-operations/talent-acquisition for staffing analysis)

Integration Points

| Skill | Integration | Data Flow | |-------|-------------|-----------| | engineering/senior-security | Feed security assessor output into deeper vulnerability analysis | SecurityAssessor results → security review input | | engineering/senior-devops | Use TCO hosting proj