--- name: tech-debt-audit-nextjs description: Audit technical debt in Next.js (App Router) projects - analyze code against checklist and generate prioritized report --- # Next.js Technical Debt Audit Skill Audit a Next.js (App Router) project for technical debt. Investigates each category from `rules/tech-debt-checklist.md` using Next.js-specific procedures, plus framework-specific checks. Outputs a prioritized report with file paths, line numbers, and remediation suggestions. ## Steps ### Step 1: Project Detection 1. Verify the project is Next.js by checking for `next.config.*` and `next` in `package.json` dependencies - If not a Next.js project → display "Error: This does not appear to be a Next.js project." and exit 2. Confirm App Router usage by checking for an `app/` directory - If only `pages/` exists → display "Warning: This project uses Pages Router. This skill targets App Router." and exit 3. Scan the project structure to understand the layout: - List route segments under `app/` - Identify `src/` vs root-level organization - Note the presence of `lib/`, `components/`, `hooks/`, `utils/`, or similar directories ### Step 2: Common Checklist Audit Investigate each category from `rules/tech-debt-checklist.md` in the Next.js context: #### Code Duplication - Search for repeated JSX patterns across components (e.g., similar form layouts, card structures) - Check for duplicated data-fetching logic across route segments - Look for repeated utility functions across `lib/`, `utils/`, or `helpers/` directories #### Architecture & Layering - Check for database or ORM calls directly in components (should be in server actions or API routes) - Verify `"use client"` components do not import server-only modules - Look for circular imports with `madge` or manual inspection of import chains #### Error Handling - List route segments missing `error.tsx` boundaries - Check API route handlers (`route.ts`) for missing try-catch or error responses - Search for empty catch blocks or swallowed errors #### Type Safety - Search for `any` type usage across `.ts` and `.tsx` files - Check component props for missing type definitions (inline `props: any` or untyped destructuring) - Look for type assertions (`as`) that bypass proper typing #### Dead Code - Identify unused exports with TypeScript or ESLint reports if available - Search for commented-out code blocks - Check for unused imports #### Constants & Configuration - Search for magic numbers and hard-coded string literals (URLs, API endpoints, thresholds) - Check for environment-specific values not using `process.env` or `next.config.*` - Look for duplicated constant definitions across files #### Component / Module Size - Identify `.tsx` files exceeding 300 lines - Flag functions or components exceeding 100 lines - Check for deeply nested JSX (4+ levels of nesting) #### Dependency Management - Check `package.json` for potentially unused dependencies - Look for duplicate packages providing the same functionality (e.g., multiple date libraries) - Note any dependencies with known deprecation warnings #### Testing - Compare route/component count against test file count to estimate coverage gaps - Check for the presence of test configuration (`jest.config.*`, `vitest.config.*`, or similar) - Identify critical paths (authentication, payment, data mutations) lacking tests #### Accessibility - Search for `` tags missing `alt` attributes (should use `next/image` with `alt`) - Check interactive elements (`