Code Complexity Audit

Process

1. Read this file
2. Read

   references/analysis-framework.md

   for detailed checklists and scoring rubrics
3. Scan the project structure and key files
4. Produce the Design Health Report

Step 1: Reconnaissance

• List project structure (2-3 levels deep)
• Identify language(s), framework(s), paradigm (OOP, functional, etc.)
• Count approximate files, modules/classes, lines of code
• Identify entry point(s) and core modules
• Check dependency files (package.json, requirements.txt, go.mod, Cargo.toml, etc.)

Step 2: Sampling Strategy

• Always read: Entry points, core domain modules, most-imported files
• Sample: 3-5 files from each major directory/package
• Prioritize: Largest, most-changed (git history), most-imported files
• Include: Public API surfaces, interfaces, error handling, tests

Step 3: Deep Analysis

references/analysis-framework.md

1. Module Depth — Deep (simple interface, rich functionality) vs shallow?
2. Information Hiding — Knowledge encapsulated or leaking?
3. Abstraction Quality — Right level? True or false abstractions?
4. Complexity Indicators — Change amplification, cognitive load, unknown unknowns

Step 4: Produce the Report

# Code Complexity Audit: [Project Name]

## Executive Summary
[2-3 sentence assessment w/ letter grade A-F]

## Scores
[Table: each dimension scored 1-10 w/ brief justification]

## Top Findings

### Critical Design Issues
[Most severe — actively creating complexity]

### Improvement Opportunities
[Moderate — could be cleaner]

### Design Strengths
[What the project does well — always include]

## Detailed Analysis
[Per-dimension subsections w/ file/line references and code examples]

## Red Flags Detected
[Reference the canonical red flags list below]

## Recommendations
[Prioritized, actionable — what to fix first and how]

## Appendix: Files Reviewed
[All files examined]

Ousterhout's Design Principles

1. Complexity is incremental — small stuff accumulates
2. Working code isn't enough — design quality matters equally
3. Continual small investments — 10-20% of time on design improvement
4. Modules should be deep — simple interfaces, rich functionality
5. Common case should be simple — good defaults, minimal config
6. Simple interface > simple implementation — callers' ease matters more
7. General-purpose modules are deeper — avoid over-specialization
8. Separate general-purpose and special-purpose — push specialization up/down
9. Different layers = different abstractions — no pass-through layers
10. Pull complexity downwards — developers suffer, not users
11. Define errors out of existence — simplify error semantics
12. Design it twice — consider alternatives before committing
13. Comments describe non-obvious things — different level of detail than code
14. Design for reading, not writing
15. Increments = abstractions, not features
16. Separate what matters from what doesn't
17. Not making design better → making it worse — continuous evolution

Red Flags

Tone & Approach

• Constructive — help, not tear down
• Always include strengths
• Specific — reference files, classes, methods, line numbers
• Actionable recommendations w/ before/after examples
• Context-aware — weekend prototype ≠ production system
• Use the project's own code in examples

Adapting to Project Size

• Small (<20 files): Read everything. Concise report.
• Medium (20-200 files): Sample. Focus on core modules.
• Large (200+ files): Heavy sampling. Focus on architecture and public APIs. Consider one subsystem deeply vs. everything shallowly.