Audit

Codebase Audit

Instructions

Perform a comprehensive, systematic audit of the codebase to identify quality issues, architectural problems, and technical debt.

Phase 1: Discovery & Planning

1. Identify scope - Determine which files/directories to audit based on user request 2. Create comprehensive file list - Use Glob to find all relevant files 3. Initialize todo list - Create a todo with one item per file to audit 4. Set up audit report - Create structured markdown report at .audit/audit-report-[timestamp].md

Phase 2: Automated Analysis

Run automated tools to supplement manual review:

• TypeScript compiler diagnostics
• ESLint (if configured)
• Grep for common patterns: TODO, FIXME, HACK, XXX, @deprecated

Phase 3: Systematic File Review

For EACH file in the todo list:

1. Read and analyze the file thoroughly 2. Check for issues in these categories:

• Deprecations: Deprecated APIs, patterns, or code marked for removal
• TODOs/FIXMEs: Unfinished work or known issues
• Architectural anti-patterns:
• God objects/classes
• Circular dependencies
• Tight coupling
• Violation of SOLID principles
• Inconsistent patterns
• Type issues:
• Use of any or unknown
• Missing type annotations
• Incorrect type usage
• Type casts that hide issues
• Code smells:
• Duplicated code
• Long functions/classes
• Complex conditionals
• Dead code
• Magic numbers/strings
• Poor naming

3. Assign severity to each finding:

• CRITICAL: Breaks functionality, security issues, data corruption risks
• HIGH: Architectural violations, major maintainability issues
• MEDIUM: Code smells, minor anti-patterns, missing types
• LOW: Style issues, minor TODOs, cosmetic improvements

4. Check for cross-file patterns - As you review, note patterns that appear across multiple files

5. Update report - Add findings to the structured report

6. Mark file as completed in todo list

Phase 4: Cross-File Analysis

After reviewing all individual files:

1. Identify systemic patterns - Issues that appear across multiple files 2. Architectural assessment - Overall system architecture health 3. Dependency analysis - Check for circular dependencies or coupling issues 4. Consistency check - Verify naming conventions, patterns are followed

Phase 5: Validation & Summary

1. Run final checks:

• TypeScript type check (tsc --noEmit or similar)
• Linting (npm run lint or similar)
• Build process if applicable

2. Generate executive summary:

• Total issues by category
• Total issues by severity
• Top 10 most critical findings

Audit Report Structure

# Audit Report - [Date]

## Executive Summary
- **Files Audited**: X
- **Total Issues Found**: Y
- **Critical**: A | **High**: B | **Medium**: C | **Low**: D

## Top 10 Critical Findings
1. [Issue description] - Severity: CRITICAL - File: path/to/file.ts:line

## Issues by Category

### Deprecations
- [Issue] - Severity - File:line

### TODOs/FIXMEs
- [Issue] - Severity - File:line

### Architectural Anti-Patterns
- [Issue] - Severity - File:line

### Type Issues
- [Issue] - Severity - File:line

### Code Smells
- [Issue] - Severity - File:line

## Cross-File Patterns
- [Pattern description and affected files]

## Automated Tool Results
- TypeScript diagnostics summary
- ESLint results summary

Critical Principles

• NEVER skip files - Audit every file in the todo list
• NEVER edit files during audit - This is read-only analysis
• NEVER provide recommendations - Only identify and report problems
• NEVER create action plans - That's a separate responsibility
• DO use memory/pinboard - Store context as you discover patterns
• DO be thorough - Think critically about each file
• DO be objective - Report what you find, not what to do about it
• DO track progress - Keep todo list updated in real-time
• DO find all relevant files - If you discover new files that should be audited, add them to the todo

Dynamic File Discovery

If during audit you discover additional files that should be reviewed: 1. Add them to the todo list immediately 2. Continue systematic review 3. Ensure no stone is left unturned