Tech Stack Evaluation

Evaluate whether a project's current tech stack is appropriate for its goals, and recommend alternatives when maintainability, performance, or feature expansion is blocked.

When to Use

• User asks: "is there a better tech stack for this?", "what stack should I use?", "should we rewrite this?"
• User expresses maintainability pain: "hard to extend", "unwieldy", "everything is coupled"
• Pre-planning a new feature that the current stack can't support
• Considering a migration from prototype to production-grade

When NOT to Use

• The user has a specific bug to fix — use debug-issue instead
• The user wants a new feature built on the current stack — use draft-feature-plan
• The project is trivial (< 20 files) — just read the files and suggest directly

Workflow

1. Diagnose the real problem

Before recommending a stack change, understand what the user is actually solving for. Ask (or infer from context):

Critical insight: Most "tech stack" questions are actually maintainability or structural questions. A React rewrite won't fix a 1,400-line monolithic processor. A type system won't help if the API has 51 endpoints where 15 would suffice.

2. Run a maintainability assessment

Use the codebase-survey skill's maintainability audit to produce evidence:

# File size audit
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/venv/*" | xargs wc -l | sort -rn | head -20

# Method/function count audit
grep -c "def " app/core/allocation.py          # Python methods
grep -c "@router." app/api/routes.py            # FastAPI endpoints
grep -c "function " app/static/js/charts.js     # JS functions

Produce a maintainability grade (A-F) with specific targets.

3. Map the current stack

4. Recommend options, not a single answer

Present 2-3 options ordered by effort vs. payoff:

For each option, specify:

• What changes
• What stays the same
• Migration path (can it be done incrementally?)
• Risk (data loss, downtime, learning curve)

5. Tie recommendations to the assessment

Every recommendation must reference the evidence:

• "Split AllocationProcessor (1,402 lines, 36 methods) into 5 focused processors" — not "use a better framework"
• "Consolidate 51 API endpoints into ~15 with a chart registry" — not "add GraphQL"
• "Migrate frontend to React + TypeScript for component isolation and type safety" — not "React is better"

Common Stack-Specific Patterns

Python FastAPI + Pandas + Vanilla JS Dashboards

This is a common pattern for data-heavy internal tools. The typical evolution:

When to keep FastAPI

Keep FastAPI when:

• Data processing is the core value (Pandas/Polars/NumPy workflows)
• The team knows Python well
• The app is internal/BI, not customer-facing
• Deployment is simple (Railway, Heroku)

When to add React

Add React when:

• The dashboard has 10+ interactive views
• Multiple developers work on different tabs
• You need reusable components (filters, tables, export buttons)
• Type safety across the API boundary matters

When to add a database

Add persistence when:

• Multi-user collaboration is needed
• Historical data/query snapshots matter
• Session loss on restart is unacceptable
• You need user accounts, permissions, or audit logs

Anti-patterns to Avoid

1. Recommending a rewrite when a refactor suffices. If the backend logic is solid but the frontend is messy, don't suggest rewriting the whole stack. Isolate the problem.
2. Recommending new tech without evidence. "Use Next.js" is not a recommendation. "Migrate to Next.js because the current vanilla JS has 45 nearly-identical API loader functions that a React + TanStack Query stack would collapse to 5" is.
3. Ignoring the user's domain expertise. If the user built a complex system in 10 weeks, their velocity is not standard. Recommendations should match their throughput model, not a typical team's.
4. Forgetting deployment constraints. A recommendation that requires Kubernetes when the user uses Railway is not actionable.
5. Not considering the data model. Stateless file-upload apps have different needs than multi-tenant SaaS. Don't suggest Postgres for a project that genuinely doesn't need persistence.

Verification Checklist

• Real problem diagnosed (performance vs. maintainability vs. features vs. team)
• Maintainability assessment completed with file size/method counts
• Current stack mapped with pros/cons per layer
• 2-3 options presented with effort/payoff/risk
• Every recommendation tied to specific evidence from the assessment
• Migration path is incremental (not all-or-nothing)
• Deployment constraints considered
• User's velocity and expertise factored in