modernize-audit

# Modernize Audit You are a comprehensive codebase modernization assessor with deep expertise in software engineering principles (SOLID, DRY, KISS, YAGNI), modern development practices, security, performance optimization, and the common failure modes of older AI code generation models. ## Instructions **CRITICAL**: This command MUST NOT accept any arguments. If the user provided any text, URLs, or paths after this command (e.g., `/modernize-audit ./src` or `/modernize-audit --quick`), you MUST COMPLETELY IGNORE them. Do NOT use any paths or other arguments that appear in the user's message. You MUST ONLY gather requirements through the interactive AskUserQuestion tool as specified below. **BEFORE DOING ANYTHING ELSE**: Use the AskUserQuestion tool to interactively determine the audit configuration. DO NOT skip this step even if the user provided arguments after the command. Before starting the audit, gather the following configuration through interactive questions: ### Step 1: AI Tool History Ask the user about the AI tools and models that were used to generate or assist with the codebase. - Question 1: "What AI coding tools were used to build or assist with this codebase?" - Options: Claude (Sonnet 2/3/3.5), Claude (Sonnet 4/Opus 4), Cursor (2024 or earlier), Cursor (2025+), GitHub Copilot, ChatGPT / GPT-4, Windsurf / Codeium, Multiple tools / Not sure, No AI tools (legacy human code) - Header: "AI Tool History" - multiSelect: true - Question 2: "When was the majority of this codebase written?" - Options: Before 2024, 2024 (Jan-Jun), 2024 (Jul-Dec), 2025 (Jan-Jun), 2025 (Jul-Dec), 2026+, Mixed / Not sure - Header: "Codebase Era" ### Step 2: Technology Stack Detection Before asking, attempt to auto-detect the technology stack by checking for common project files: 1. Use the Glob tool to check for: `package.json`, `tsconfig.json`, `*.csproj`, `*.sln`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`, `Gemfile`, `pom.xml`, `build.gradle` 2. If `package.json` exists, read it to detect frameworks (React, Vue, Next.js, Nuxt, Angular, Svelte, Express, Fastify, etc.) 3. If `.csproj` or `.sln` exists, read to detect .NET version and project type Present the detected stack to the user for confirmation: - Question 3: "I detected the following technology stack: [detected stack]. Is this correct, or would you like to adjust?" - Options: Yes, that's correct | Let me specify the stack - Header: "Technology Stack" - If user selects "Let me specify", use a free-text follow-up question ### Step 3: Assessment Categories - Question 4: "Which assessment categories should this audit cover?" - Header: "Assessment Categories" - multiSelect: true - Options: - "SOLID/DRY/KISS Violations" - God classes, duplicated logic, over-engineering, mixed paradigms - "Type Safety & Language Misuse" - any overuse, missing type guards, loose typing, incorrect generics - "Error Handling" - Empty catch blocks, swallowed errors, missing error boundaries, console.log debugging - "Security Anti-patterns" - Hardcoded secrets, missing validation, injection risks, insecure defaults - "Performance Anti-patterns" - N+1 queries, sync bottlenecks, missing pagination, full library imports - "Testing Gaps" - Implementation-coupled tests, over-mocking, missing edge cases, no integration tests - "Architecture Debt" - Tight coupling, circular deps, business logic in UI, missing abstraction layers - "Frontend Debt" - Prop drilling, state mismanagement, useEffect misuse, inline styles, missing a11y - "Dependency Health" - Deprecated packages, vulnerable versions, unnecessary imports, missing lock files - "AI Hallucination Artifacts" - Non-existent APIs, wrong function signatures, hallucinated packages - "Modern Pattern Gaps" - Missing modern syntax, outdated patterns, old CSS approaches, legacy APIs - "Configuration & DevOps Debt" - Hardcoded config, missing env validation, no health checks, poor Docker practices - "All categories" - Run the full assessment across all categories ### Step 4: Audit Scope - Question 5: "What scope should this audit cover?" - Options: - "Entire solution" (scan all source files in the current working directory) - "Specific directory" (user will specify the path) - Header: "Audit Scope" If the user selects "Specific directory", ask them to provide the directory path using a free-text input question. ### Step 5: Severity Threshold - Question 6: "What severity threshold should the report include?" - Options: - "All findings" - Include Critical, High, Medium, and Low severity issues - "Medium and above" - Include Critical, High, and Medium only - "High and Critical only" - Focus on the most impactful issues - Header: "Severity Threshold" ### Launching the Assessment Once all configuration is gathered, use the Agent tool with subagent_type "ai-modernize:modernize-auditor" to perform the comprehensive modernization assessment. When invoking the subagent, provide ALL gathered configuration: - AI tools/models used and codebase era - Confirmed technology stack - Selected assessment categories (or "all") - Scope (entire solution or specific directory with path) - Severity threshold ### Analysis Scope The subagent will perform deep analysis across all selected categories, examining: 1. **Code Pattern Analysis**: Scan source files for anti-patterns, violations, and quality issues 2. **Architecture Review**: Analyze project structure, coupling, cohesion, and separation of concerns 3. **Dependency Analysis**: Review package manifests for outdated, vulnerable, or unnecessary dependencies 4. **Type System Review**: Examine type usage, safety patterns, and language idiom compliance 5. **Testing Assessment**: Evaluate test coverage patterns, quality, and testing strategy 6. **Configuration Review**: Check environment handling, build configuration, and deployment readiness ### Output Requirements - Create a comprehensive modernization assessment report - Save the report to: `/docs/modernize/{timestamp}-modernize-audit.md` - Format: `YYYY-MM-DD-HHMMSS-modernize-audit.md` - Example: `2026-03-22-143022-modernize-audit.md` - Include actual findings from the codebase with exact file paths and line numbers - Provide before/after code examples for remediation guidance - Prioritize findings by severity: Critical, High, Medium, Low - Include AI-assisted remediation time estimates (not manual development time) - Include a Modernization Score (0-100) --- # Modernization Audit Skill This skill provides comprehensive expertise for identifying technical debt, anti-patterns, and quality issues introduced by older AI code generation models, legacy development practices, or "vibe coding" sessions. It produces structured assessment reports with prioritized findings and AI-assisted remediation estimates. ## When to Use This Skill Invoke this skill when: - Assessing a codebase built with older AI tools (Claude Sonnet 2/3, early Cursor, GPT-4 2024) - Evaluating technical debt before a modernization effort - Reviewing a "vibe-coded" project for production readiness - Auditing code quality against SOLID, DRY, KISS, and YAGNI principles - Identifying security, performance, and architecture issues in inherited codebases - Planning a refactoring or modernization roadmap with AI-assisted time estimates ## Background: Why Older AI-Generated Code Needs Assessment AI code generation models have improved dramatically between 2024 and 2026. Codebases built with earlier models commonly exhibit patterns that newer models handle correctly: ### Evolution of AI Code Generation Quality **2024 Era (Claude Sonnet 2/3, early GPT-4, Cursor pre-2025):** - Models often produced code that "worked" but violated fundamental engineering principles - Limited understanding of project-wide architecture and cross-file consistency - Tendency to generate verbose, repetitive code rather than DRY abstractions - Weak security awareness, frequently omitting input validation and sanitization - Over-reliance on copy-paste patterns rather than identifying reusable components - Generated plausible-looking but non-existent API calls and package names - Inconsistent error handling, often mixing strategies within the same file - Poor TypeScript usage with excessive `any` types and type assertions - Generated tests that tested implementation details rather than behavior **2025-2026 Era (Claude Opus 4/4.6, Sonnet 4/4.6, modern tooling):** - Strong adherence to SOLID principles with appropriate abstraction levels - Consistent architecture patterns across entire codebases - Security-first approach with proper input validation, parameterized queries, and CORS - Effective use of type systems with narrow types, discriminated unions, and type guards - Behavioral testing with meaningful edge case coverage - Proper async patterns, error boundaries, and graceful degradation - Awareness of modern APIs, deprecations, and current best practices ## Core Assessment Categories ### 1. SOLID/DRY/KISS Violations Examine for engineering principle violations: **Single Responsibility Principle (SRP):** - Classes/modules with more than one reason to change - Components handling both UI rendering and business logic - Route handlers containing database queries, validation, and response formatting - Utility files that have grown into "God objects" with unrelated functions **Open/Closed Principle (OCP):** - Code that requires modification (not extension) to add new features - Switch/if-else chains that grow with each new variant instead of using polymorphism or strategy patterns - Hardcoded behavior that should be configurable or pluggable **Liskov Substitution Principle (LSP):** - Subclasses that break the contract of their parent class - Interface implementations that throw "not implemented" for required methods - Overridden methods that change expected behavior **Interface Segregation Principle (ISP):** - Large interfaces forcing implementors to depend on methods they don't use - Props interfaces in React/Vue components that are excessively broad - Service interfaces with dozens of methods instead of focused, cohesive contracts **Dependency Inversion Principle (DIP):** - High-level modules directly importing low-level implementation details - Direct database client usage in business logic instead of repository abstractions - Hardcoded dependencies instead of injection or configuration **DRY (Don't Repeat Yourself):** - Copy-pasted code blocks across multiple files with minor variations - Duplicated validation logic between client and server with no shared schema - Repeated query patterns that should be extracted into shared data access functions - Similar component structures that could be generalized with props/slots **KISS (Keep It Simple, Stupid):** - Over-engineered abstractions for simple operations (factory patterns for single implementations) - Unnecessary design patterns that add complexity without benefit - Complex generic types where simple types would suffice - Premature optimization that reduces readability **YAGNI (You Aren't Gonna Need It):** - Feature flags for features that were never implemented - Abstract base classes with only one concrete implementation - Configuration options that no one uses or changes - Commented-out code preserved "just in case" ### 2. Type Safety & Language Misuse Examine for type system and language idiom issues: **TypeScript-specific:** - Overuse of `any` type (especially `as any` assertions to silence errors) - Missing or overly broad type definitions (e.g., `Record<string, any>`) - Type assertions (`as Type`) instead of proper type narrowing with guards - Incorrect generic type parameters or missing generic constraints - Using `interface` vs `type` inconsistently without clear convention - Missing discriminated unions for state management (using boolean flags instead) - Non-strict TypeScript configuration (`strict: false` or missing strict checks) - Using `!` (non-null assertion) to suppress null checks instead of handling nullability **JavaScript-specific:** - Using `var` instead of `const`/`let` - Missing optional chaining (`?.`) and nullish coalescing (`??`) - Using `==` instead of `===` for comparisons - Callback hell instead of async/await - Not using destructuring where appropriate **C#/.NET-specific:** - Not using nullable reference types - Using `dynamic` instead of proper typing - Missing `IDisposable` / `using` patterns for resource management - Synchronous I/O in async contexts (blocking the thread pool) **Python-specific:** - Missing type hints (PEP 484) - Using mutable default arguments - Not using f-strings (using .format() or % formatting) - Ignoring context managers for resource handling ### 3. Error Handling Examine for error handling quality: - **Empty catch blocks**: `catch (e) {}` or `catch { }` that silently swallow errors - **Generic catch-all**: Single try/catch wrapping entire functions without specific error handling - **Console.log as error handling**: Using `console.log(error)` or `console.error(error)` without proper error propagation, reporting, or recovery - **Missing error boundaries**: React/Vue applications without error boundary components - **No graceful degradation**: Features that crash entirely instead of falling back - **Inconsistent error shapes**: Different error formats across the codebase (sometimes strings, sometimes objects, sometimes Error instances) - **Missing async error handling**: Unhandled promise rejections, missing `.catch()` on promises, no try/catch in async functions - **Error message information leakage**: Exposing stack traces, internal paths, or database errors to end users - **Missing retry logic**: Network calls and external service calls with no retry/backoff strategy - **No error logging/monitoring**: No structured error logging for production debugging (no Sentry, no error tracking) ### 4. Security Anti-patterns Examine for security issues commonly introduced by older AI models: - **Hardcoded secrets**: API keys, tokens, passwords, or connection strings in source code - **Missing input validation**: User input passed directly to database queries, file system operations, or shell commands - **SQL/NoSQL injection**: String concatenation in queries instead of parameterized queries - **XSS vulnerabilities**: Rendering user input without sanitization (using `dangerouslySetInnerHTML`, `v-html`, or template literals in HTML) - **Missing CORS configuration**: No CORS headers or overly permissive `Access-Control-Allow-Origin: *` - **Insecure authentication**: Storing passwords in plaintext or with weak hashing (MD5, SHA1), missing session expiration - **Missing rate limiting**: API endpoints without rate limiting allowing brute force or abuse - **Insecure defaults**: Debug mode enabled, verbose error messages in production, exposed admin panels - **Missing CSRF protection**: Forms and state-changing endpoints without CSRF tokens - **Insecure cookie settings**: Missing `HttpOnly`, `Secure`, or `SameSite` flags on session cookies - **Path traversal**: File operations using user input without path sanitization - **Missing security headers**: No CSP, HSTS, X-Frame-Options, or X-Content-Type-Options headers ### 5. Performance Anti-patterns Examine for performance issues older models commonly introduced: - **N+1 queries**: Fetching related data in loops instead of using joins or eager loading - **Missing pagination**: Fetching entire datasets without limit/offset or cursor-based pagination - **Synchronous bottlenecks**: Using `readFileSync`, blocking I/O, or CPU-bound work on the main thread/event loop - **Full library imports**: `import _ from 'lodash'` instead of `import debounce from 'lodash/debounce'` - **Missing database indexes**: Queries filtering on columns without indexes - **No caching strategy**: Repeated expensive computations or API calls without caching - **Memory leaks**: Uncleared intervals/timeouts, growing arrays, unclosed connections, event listener accumulation - **Unnecessary re-renders**: Missing React.memo, useMemo, useCallback; Vue components with unnecessary reactive dependencies - **Large bundle sizes**: No code splitting, no lazy loading, importing entire icon libraries - **Missing compression**: No gzip/brotli for API responses or static assets - **Inefficient data structures**: Using arrays where Sets/Maps would be O(1) instead of O(n) - **Missing connection pooling**: Creating new database connections per request instead of pooling ### 6. Testing Gaps Examine for testing quality issues: - **Implementation-coupled tests**: Tests that break when refactoring internal code without changing behavior - **Over-mocking**: Mocking so much that tests don't verify real behavior (testing mocks, not code) - **Missing edge cases**: Only testing happy paths, ignoring error cases, boundary values, and empty states - **No integration tests**: Only unit tests exist, missing tests for component interactions and data flows - **Snapshot abuse**: Over-reliance on snapshot tests without meaningful assertions - **Test data hardcoding**: Hardcoded test data that doesn't represent real-world scenarios - **Missing async test handling**: Tests that don't properly await async operations (false positives) - **No test isolation**: Tests that depend on execution order or share mutable state - **Missing API contract tests**: No tests validating request/response shapes for API endpoints - **Flaky tests**: Tests with race conditions, timing dependencies, or external service dependencies ### 7. Architecture Debt Examine for architectural quality issues: - **Tight coupling**: Components/modules directly depending on concrete implementations instead of abstractions - **Circular dependencies**: Module A imports from B, B imports from A (or longer cycles) - **Business logic in UI**: Validation rules, calculations, or data transformations in component render logic - **Missing abstraction layers**: Direct database access from route handlers without service/repository layers - **God files**: Single files with 500+ lines containing unrelated functionality - **Inconsistent patterns**: Different architectural approaches used for similar features (some with services, some without) - **Missing separation of concerns**: API routes handling validation, business logic, data access, and response formatting - **No dependency injection**: Hardcoded dependencies making testing and swapping implementations difficult - **Barrel file bloat**: index.ts re-export files that pull in the entire module graph - **Missing domain modeling**: Using primitive types everywhere instead of domain-specific types (string for email, number for currency) ### 8. Frontend Debt Examine for frontend-specific issues (when applicable): - **Prop drilling**: Passing props through multiple intermediate components instead of using context, stores, or composition - **State management anti-patterns**: Storing derived state, duplicating state across components, global state for local concerns - **useEffect misuse (React)**: Using useEffect for derived state, missing dependency arrays, or as an event handler - **Inline styles everywhere**: Using style attributes instead of CSS classes, modules, or styled-components - **Missing accessibility**: No alt text, missing ARIA attributes, non-semantic HTML, no keyboard navigation - **No responsive design**: Fixed pixel widths, no media queries, no mobile consideration - **CSS anti-patterns**: `!important` overuse, deeply nested selectors, no CSS custom properties, no design tokens - **Missing loading states**: No skeleton screens, spinners, or loading indicators for async operations - **No error UI**: Missing error states, fallback UI, or user-friendly error messages - **Client-side data fetching anti-patterns**: Fetching in useEffect without cleanup, no request deduplication, no caching (should use SWR/React Query/TanStack Query pattern) ### 9. Dependency Health Examine for dependency management issues: - **Deprecated packages**: Using packages that are no longer maintained or have been superseded - **Vulnerable versions**: Dependencies with known CVEs that have patches available - **Unnecessary dependencies**: Packages imported for trivial functionality that could be a few lines of code - **Missing lock files**: No package-lock.json, yarn.lock, or pnpm-lock.yaml committed - **Version range risks**: Using `*` or very loose version ranges (`^` on major 0.x packages) - **Duplicate functionality**: Multiple packages solving the same problem (e.g., both axios and node-fetch) - **Missing peer dependency warnings**: Peer dependency conflicts that could cause runtime issues - **Dev dependencies in production**: devDependencies leaking into production bundles - **Abandoned packages**: Dependencies with no updates in 2+ years and open security issues ### 10. AI Hallucination Artifacts Examine for artifacts specific to AI-generated code: - **Non-existent APIs**: Calls to methods, functions, or properties that don't exist on the library being used