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