charlesjones-dev/claude-code-plugins-dev/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

Arguments

The text typed after the command holds the arguments. In Claude Code it is inserted here: $ARGUMENTS. In other agents, read it from the user's message. It may be empty.

Each argument answers one of the configuration questions below, and that question is then skipped:

Quote values that contain spaces. If the arguments are plain language instead (for example "only security, high and critical"), map what clearly matches a setting and treat the rest as missing. If the path doesn't exist, tell the user and stop.

Examples:

• /modernize-audit asks all six questions.
• /modernize-audit src/api categories=security,performance audits src/api for those two categories, then asks about AI tools, era, stack and severity.
• /modernize-audit . ai=copilot era=2024 stack=auto categories=all severity=medium asks nothing and audits the whole repository.
• /modernize-audit src/services --defaults asks nothing and audits src/services with the defaults.
• /modernize-audit src/services/auth.ts --defaults severity=high asks nothing, audits one file and reports only High and Critical findings.

Gathering the Configuration

Ask only for the settings the arguments don't supply, using the questions in Steps 1-5 below and skipping any question the arguments answer. When the arguments supply all six settings, ask nothing and start the assessment.

If AskUserQuestion isn't available, ask in plain text and wait for the answer.

Don't ask anything, and use the defaults below for every setting the arguments leave out, when either of these is true:

• The arguments include --defaults.
• No one can answer, as in an unattended run such as a scheduled or headless session.

Mark each default "(default)" in the report's Audit Configuration table.

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 3-era models, 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

If the arguments give a stack, use it without asking. With stack=auto or --defaults, or in an unattended run, use the detected stack without asking. Otherwise, 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 file or directory" (user will specify the path)
• Header: "Audit Scope"

If the user selects "Specific file or directory", ask them for the path using a free-text input question. If the path doesn't exist, tell the user and stop.

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"

Running the Assessment

Once the configuration is settled, run the assessment yourself in this session. Follow the Audit Methodology below, check each selected category against the checklist in references/categories.md, and write the report with the Report Template.

Fit the work to the scope and settings:

• A single file: analyze it in full depth across every selected category that applies to it.
• A directory, or the entire solution: analyze every source file under it, recursively.
• Applicability: when all categories are selected, skip any that can't apply to the scope, such as Frontend Debt for backend-only code. List each skipped category as "not applicable" in the Categories Assessed row, and leave it out of the Category Summary and the Modernization Score. When the configuration names categories, assess every one of them.
• Severity threshold: leave out findings below the threshold.

Analysis Scope

Analyze every selected category in depth, 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, relative to the repository root
• Format: YYYY-MM-DD-HHMMSS-modernize-audit.md
• Example: 2026-03-22-143022-modernize-audit.md
• Verify every finding against the actual source code before reporting it
• 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)
• Include the phased Modernization Roadmap
• Once the report is saved, tell the user its path, the Modernization Score and the number of findings at each severity

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 3-era models, 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
• Checking one file or directory quickly, without the setup questions (--defaults)

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