tech-debt-analyzer

name	tech-debt-analyzer
description	Identify and address technical debt in a React + TypeScript codebase. Use this skill when the user asks to find tech debt, reduce complexity, clean up code smells, refactor legacy patterns, or improve code quality. Triggers on mentions of technical debt, code smells, refactor, cleanup, complexity, legacy code, or maintainability.

Technical Debt Analyzer

Overview

Analyze React + TypeScript code for common sources of technical debt and provide actionable remediation steps. Focus on patterns that slow teams down over time rather than stylistic nitpicks.

What to Look For

Component-Level Debt

• Components longer than ~250 lines — suggest extraction
• Prop drilling deeper than 2 levels — suggest context or Zustand store
• Inline styles or hardcoded strings — suggest Tailwind classes or constants
• Class components — migrate to functional components with hooks
• any type usage — replace with proper TypeScript interfaces
• Disabled ESLint rules via eslint-disable comments — resolve the underlying issue

Hook-Level Debt

• useEffect with missing or overly broad dependency arrays
• Multiple related useState calls that should be a single useReducer or Zustand store
• Data fetching inside useEffect — migrate to React Query (useQuery / useMutation)
• Custom hooks that do too many things — split by responsibility

Architecture-Level Debt

• Business logic inside components — extract to services/ or utils/
• API calls scattered across components — consolidate in services/
• Duplicated type definitions — consolidate in types/
• Missing or inconsistent error boundaries
• Large barrel files (index.ts) re-exporting everything — causes bundle bloat

Dependency Debt

• Outdated packages with known CVEs
• Multiple libraries solving the same problem (e.g., both axios and fetch wrappers)
• Unused dependencies in package.json

Output Format

For each issue found, provide:

1. Location — file path and line range
2. Category — one of: Component, Hook, Architecture, Dependency
3. Severity — High (blocks features / causes bugs), Medium (slows development), Low (cosmetic / minor friction)
4. Problem — one-sentence description
5. Remediation — concrete steps or code example to fix it

Prioritization

Order findings by:

1. High severity items first
2. Within same severity, prefer items that touch shared/reused code
3. Group related items that can be fixed together

Example

User Request

"Can you check this component for tech debt?"

Expected Analysis

## Tech Debt Report: UserDashboard.tsx

### 1. Component too large (Medium)
- **Lines**: 1–340
- **Problem**: Component handles data fetching, filtering, sorting, and rendering
- **Fix**: Extract `useUserDashboardData` hook for data logic, split
  `DashboardFilters` and `DashboardTable` into child components

### 2. Direct API call in useEffect (Medium)
- **Lines**: 45–67
- **Problem**: Raw fetch inside useEffect with manual loading/error state
- **Fix**: Replace with React Query:
  ```tsx
  const { data, isLoading, error } = useQuery({
    queryKey: ['users', filters],
    queryFn: () => userService.getUsers(filters),
  });

3. TypeScript any on API response (High)

• Lines: 48, 52
• Problem: Response typed as any, losing type safety downstream
• Fix: Define interface UserListResponse in types/user.ts and type the query function return