Codebase analysis

Codebase Analysis

Overview

Systematically analyze a codebase and produce a structured, evidence-backed architecture report. Every claim must cite actual file paths, function names, or code snippets — never fabricate.

For large codebases, output is hierarchical multi-file — not a single monolithic document.

Output Language

Match the user's language. If the user speaks Chinese, write the report in Chinese; if English, write in English; and so on.

Exceptions — always keep in English regardless of output language:

• Section headings and table column headers (e.g., ## Overall Architecture, | Module | Path | ...)
• Code identifiers: file paths, function names, class names, variable names, import statements
• Technical terms with no widely-accepted translation (e.g., middleware, ORM, circuit breaker, monorepo)
• Summary Card / Module Card field labels (e.g., Project:, Module:, Source:)
• Mermaid diagram node labels and annotations
• Git metadata (commit hash, branch name, tag)
• The <!-- Last analyzed: ... --> footer

When in doubt, keep the term in English and add a brief parenthetical in the user's language on first use. Example: "采用了 circuit breaker（熔断器）模式"

When to Use

• User asks to analyze/understand/document a codebase
• User asks for architecture overview, module inventory, or dependency graph
• User asks about design philosophy, data flow, or API surface
• Onboarding to a new project and need a structured understanding

When NOT to use:

• Analyzing a single file or function (just read it)
• Debugging a specific bug (use systematic-debugging)
• Planning implementation (use writing-plans)

---

Phase 0: Scope & Scale Assessment

Before writing anything, determine what to analyze and how to output.

Scope Mode

digraph scope {
    rankdir=TB;
    node [shape=box];

    Q["User request"];
    A{"Scope specified?"};
    FULL["FULL mode\n(entire codebase)"];
    FOCUS["FOCUS mode\n(single module/directory)"];
    DIFF["DIFF mode\n(version comparison)"];

    Q -> A;
    A -> FULL [label="no, or 'analyze the project'"];
    A -> FOCUS [label="'analyze src/auth' or specific path"];
    A -> DIFF [label="'what changed between v1 and v2'"];
}

• FULL mode: Analyze entire codebase. Produce L0 + all L1 + L2 where needed.
• FOCUS mode: Analyze one module as if it were a standalone project. Output to docs/architecture/<module-name>/ (or update in-place if it already exists). Produce ONE _overview.md using L1 template, with L2 expansion for its sub-modules. Include a brief "Context" section at the top showing where this module sits in the larger system (one Mermaid diagram highlighting this module's position).
• DIFF mode: Compare two versions. Produce _evolution.md only (in docs/architecture/), with optional L1 updates for changed modules.

Scale (Output Strategy)

Only applies to FULL mode:

digraph scale {
    rankdir=TB;
    node [shape=box];

    A["Count top-level modules\n(ls src/ or equivalent)"];
    B{">= 4 modules OR\nany module has >= 3 subdirs?"};
    C["MULTI-FILE mode"];
    D["SINGLE-FILE mode"];

    A -> B;
    B -> C [label="yes"];
    B -> D [label="no"];
}

SINGLE-FILE mode: One _overview.md containing all L0 sections. For each module in the Module Inventory, expand L1 content inline as a ### subsection (Purpose, Public API, Key Code Paths, Risks) instead of linking to separate files. No separate _dependency-graph.md or _integrations.md — include those sections inline.

MULTI-FILE mode: A directory tree of documents mirroring the codebase hierarchy. Use for anything non-trivial.

Incremental Update

If docs/architecture/ (or user-specified output dir) already exists with prior analysis:

1. Extract <last-analyzed-commit> from the HTML comment footer in _overview.md (e.g., <!-- Last analyzed: a1b2c3d 2026-04-10 -->)
2. Run git diff --name-only <last-analyzed-commit>..HEAD to find changed files
3. Map changed files to modules
4. Only regenerate L1/L2 docs for affected modules
5. Always regenerate L0 _overview.md (Summary Card, Module Inventory, Dependency Graph may have changed)
6. Append a new section to _evolution.md for this diff range
7. Update the footer in each regenerated file: <!-- Last analyzed: <commit-hash> <date> -->

---

Phase 1: Analysis Procedure

Same regardless of output mode:

1. Git context (if .git/ exists):
   • git remote get-url origin → repo URL
   • git describe --tags --always → latest tag or commit hash
   • git log -1 --format="%H %ai" → current commit + date
   • git branch --show-current → current branch
2. Read project manifest (package.json / pyproject.toml / Cargo.toml / go.mod)
3. Read README.md + docs/ directory
4. Map top-level directory tree (ls -R depth 3)
5. Read each module's entry file (index.ts / __init__.py / mod.rs / main.go)
6. Trace 1-2 representative end-to-end code paths
7. For MULTI-FILE mode: repeat steps 5-6 for each module at depth

---

Phase 2: Output

Output Directory Structure (MULTI-FILE mode)

Write all files under a user-specified directory (default: docs/architecture/).

docs/architecture/
├── _overview.md              # L0: whole-project overview (always first)
├── _dependency-graph.md      # L0: global dependency graph
├── _integrations.md          # L0: external systems map
├── _evolution.md             # L0: version diff (if requested)
├── module-a/
│   ├── _overview.md          # L1: module-a deep dive
│   ├── sub-module-x/
│   │   └── _overview.md      # L2: sub-module-x deep dive
│   └── sub-module-y/
│       └── _overview.md      # L2: sub-module-y deep dive
├── module-b/
│   └── _overview.md          # L1: module-b deep dive
└── module-c/
    └── _overview.md          # L1: module-c deep dive

Rules:

• Directory names mirror source code module names exactly
• Every directory has exactly one _overview.md (underscore prefix = meta-doc, not code)
• Only create sub-module directories when a module has >= 3 cohesive subdirectories in source
• Depth cap: 3 levels (L0 → L1 → L2). Beyond L2, document inline within L2's _overview.md

Navigation

Every _overview.md must begin with a nav block (L0's nav block comes AFTER the Executive Summary):

> **Parent:** [Project Overview](../_overview.md)
> **Children:** [sub-module-x](./sub-module-x/_overview.md) | [sub-module-y](./sub-module-y/_overview.md)
> **Source:** `src/module-a/`

• L0: Executive Summary first, then nav block with only Children + Source links (no Parent)
• L1/L2: nav block first (no Executive Summary at these levels)
• Leaf nodes have no Children links
• Source always points to the actual code directory being documented

L0 nav example:

> **Children:** [auth](./auth/_overview.md) | [payments](./payments/_overview.md) | [core](./core/_overview.md)
> **Related:** [Dependency Graph](./_dependency-graph.md) | [Integrations](./_integrations.md) | [Evolution](./_evolution.md)
> **Source:** project root

---

L0: Project Overview (_overview.md)

The top-level document. Must be self-contained and scannable — a reader should understand the entire system from this one file without opening any child docs.

L0 Sections

0. Executive Summary

This is the FIRST thing in every _overview.md at L0 level. Written in natural language paragraphs, not tables or bullet lists.

Must contain three parts:

Part A — What & Why (2-3 sentences): What does this project do? What problem does it solve? Who is the target user?

Part B — Architectural Impression (2-3 sentences): Your professional assessment of the codebase's structure and design thinking. Mention standout qualities (clean separation, clever abstractions, pragmatic trade-offs) and notable concerns (over-engineering, inconsistency, tech debt). Be specific — cite a pattern or module as evidence, not generic praise.

Part C — Git Identity (code block, if .git/ exists):

Repository:     [git remote URL, or "local-only (no remote)"]
Branch:         [current branch]
Version:        [latest tag, or "untagged"]
Commit:         [short hash + date, e.g., "a1b2c3d (2026-04-10)"]

If not a git repo, replace with: Source: [absolute path to project root]

Example:

Litestar is a high-performance async Python web framework built on Starlette and Pydantic. It targets developers who want FastAPI-like ergonomics with more opinionated structure and first-class dependency injection.

The codebase demonstrates strong layered thinking — core/ owns all domain abstractions, handlers/ are thin routing glue, and plugins/ extend behavior without touching internals. The use of Protocol-based typing throughout core/types.py is notably disciplined. The main concern is the utils/ module which has become a catch-all with 40+ files and no clear internal boundary.

Repository:     https://github.com/litestar-org/litestar
Branch:         main
Version:        v2.15.0
Commit:         f7e3a21 (2026-03-28)

1. Summary Card

Project:            [name]
Architecture:       [e.g., Modular Monolith]
Entry Point(s):     [e.g., src/main.ts]
Test Command:       [e.g., npm test]
Build Command:      [e.g., npm run build]
Module Count:       [n]
Total LOC:          [n (via cloc or wc -l, exclude vendor/generated)]
Est. Test Coverage: [low/medium/high]
Top Risk:           [one-line summary]

2. Design Philosophy & Conventions

Bullet list with evidence:

• Core philosophy (convention-over-config, explicit-over-implicit, etc.)
• Naming conventions (files, dirs, classes, functions, variables)
• Code organization pattern (feature-based, layer-based, hybrid)
• Error handling strategy (exceptions, result types, error codes)
• Configuration approach (env vars, config files, feature flags)

3. Overall Architecture

• One-paragraph system summary
• Architecture style classification
• Mermaid layered diagram: entry points → core/domain → infrastructure/adapters → external systems
• Data flow: how a typical request travels input → output

4. Technology Stack

Full inventory of the project's technology choices, organized by layer. Source of truth: derive from actual files (package.json, go.mod, requirements.txt, Dockerfile, CI configs, import statements), NOT from README claims alone.

Layer	Technology	Version	Purpose	Config / Evidence
Language	TypeScript	5.4	Primary language	tsconfig.json
Runtime	Node.js	20 LTS	Server runtime	Dockerfile, .nvmrc
Framework	Express	4.18	HTTP server	package.json
ORM / DB client	Prisma	5.10	Database access	prisma/schema.prisma
Database	PostgreSQL	16	Primary storage	docker-compose.yml
Cache	Redis	7	Session + query cache	src/config/cache.ts
Auth	Passport.js	0.7	OAuth / local auth	src/auth/strategies/
Testing	Jest + Supertest	29 / 6.3	Unit + integration tests	jest.config.ts
Linting	ESLint + Prettier	8 / 3	Code style enforcement	.eslintrc.js, .prettierrc
CI/CD	GitHub Actions	—	Build, test, deploy	.github/workflows/
Container	Docker	—	Production packaging	Dockerfile, docker-compose.yml
Infra	AWS (ECS + RDS)	—	Cloud deployment	terraform/

Rules:

• Every row must have evidence — a file path or import statement proving the technology is actually used
• Mark version as "—" if not pinned or not determinable
• Omit layers that are not applicable — only show what actually exists in the project
• Distinguish between direct dependencies (code imports it) and infrastructure dependencies (runs alongside but code doesn't directly import, e.g., Nginx reverse proxy)

Stack Assessment (1-2 sentences): Is the stack coherent? Are there redundant technologies solving the same problem (e.g., both Axios and fetch, both Redux and Zustand)? Are there notably outdated versions with migration pressure?

5. Module Inventory (Registry)

This is the master index — every module in one table, with links to deep-dive docs.

Module	Source Path	Responsibility (one line)	LOC	Files	Deep Dive
auth	src/auth/	Authentication & session management	2.4k	18	→ detail
payments	src/payments/	Payment processing & billing	5.1k	32	→ detail
core	src/core/	Shared domain models & types	1.2k	8	→ detail

Rules:

• One row per module, no sub-modules here (those go in the module's own deep dive)
• "Responsibility" is ONE line — forces clarity
• LOC and Files give quick size intuition
• SINGLE-FILE mode: replace "Deep Dive" column with inline expansion per module

How to gather LOC: cloc --by-file --include-lang=<lang> <path> or find <path> -name '*.ts' | xargs wc -l

6. Global Dependency Graph

Link to _dependency-graph.md or inline if small. Mermaid diagram + analysis:

• Circular dependencies?
• Most depended-upon module? (= core)
• Most dependency-heavy module? (= fragile)
• Dependency direction consistency? (outer → inner)

7. Concurrency & Async Model

Describe how the system handles concurrent work:

• Threading model: single-threaded event loop (Node.js), multi-threaded (Java/Go), actor-based (Erlang/Akka), coroutine-based (Python asyncio, Kotlin), or mixed?
• Async patterns: callbacks, Promises/Futures, async/await, channels, message passing?
• Shared state protection: mutexes, RWLocks, atomic operations, immutable data, STM, or "hope for the best"?
• Concurrency boundaries: which modules run concurrently? Where are the synchronization points?

If not applicable (pure CLI tool, batch script), state: "Single-threaded, no concurrency model."

Evidence: cite actual lock usage, channel declarations, async function signatures, thread pool configs.

8. Error Handling & Propagation

Trace how errors flow from origin to user:

DB connection timeout
  → repository/user.ts throws ConnectionError
    → service/auth.ts catches → wraps as AuthServiceError
      → controller/auth.ts catches → maps to HTTP 503
        → middleware/error.ts formats → { error: "Service unavailable", code: "AUTH_DB_DOWN" }
          → User sees: 503 response

Then assess:

• Strategy: exceptions, Result/Either types, error codes, or inconsistent mix?
• Error boundaries: where are errors caught and translated? Are there clear layers?
• Unhandled paths: any catch {} (swallowed), // TODO: handle error, or missing error cases?
• Error types: is there a hierarchy? Custom error classes or raw strings?
• User-facing errors: are internal details leaked? Are error messages helpful?

9. External Systems Integration

Link to _integrations.md or inline if few integrations.

10. API Surface

For any exposed interfaces (HTTP, GraphQL, gRPC, CLI commands, library exports), list them grouped by domain:

Endpoint / Command	Method	Input	Output	Auth Required?	Handler Location
POST /api/auth/login	POST	{ email, password }	{ token, user }	No	src/routes/auth.ts:23
GET /api/users/:id	GET	path param id	User	Yes (Bearer)	src/routes/users.ts:45
cli: migrate	CLI	--target <version>	stdout log	N/A	src/cli/migrate.ts:10

If the API is large (20+ endpoints), summarize by domain with counts and link to module-level L1 docs for full listings:

Domain	Endpoint Count	Base Path	Detail
Auth	4	/api/auth/	→ auth module
Users	6	/api/users/	→ users module
Payments	8	/api/payments/	→ payments module

11. Language/Framework Idiom Assessment

Evaluate whether the code follows established best practices for its language and framework:

Pattern	Status	Evidence	Impact
[framework-specific idiom]	✅ Followed / ⚠️ Partial / ❌ Violated	file:line	[consequence]

Examples by ecosystem:

• React: Component composition vs prop drilling? Hooks usage (useEffect deps, custom hooks)? State management colocation? Render optimization (memo, useMemo, useCallback — overused or underused)?
• Go: Error handling (wrapped errors vs raw strings)? Context propagation? Interface segregation? Goroutine lifecycle management? defer for cleanup?
• Python: Type hints coverage? Context managers for resources? Generator usage for large data? __init__.py exports? Pydantic vs dataclass choice?
• TypeScript: Strict mode? any escape hatches? Discriminated unions vs type assertions? Barrel exports?
• Rust: Ownership patterns? Error handling (thiserror/anyhow)? Unsafe usage? Trait design?
• Java/Kotlin: Dependency injection patterns? Null safety? Stream API usage? Exception hierarchy?

Only cover the language(s) actually used. Focus on patterns that impact maintainability and correctness, not style preferences.

12. Cross-Cutting Concerns

For each concern that exists, state how it's implemented. Omit concerns that are not applicable.

Concern	Exists?	Implementation	Evidence
Logging	✅	Winston, structured JSON, levels: error/warn/info	src/config/logger.ts
Auth / AuthZ	✅	Passport.js + RBAC middleware	src/auth/, src/middleware/rbac.ts
Input validation	⚠️ Partial	Zod on API layer only, no DB-level constraints	src/routes/validators/
Rate limiting	❌	—	—
Caching	✅	Redis with 300s TTL	src/config/cache.ts
i18n	❌	—	—
Observability	⚠️ Partial	Prometheus metrics, no distributed tracing	src/metrics/
DB migrations	✅	Prisma Migrate	prisma/migrations/

13. Build, Test & Deploy

• Build system and commands
• Test framework and run command
• CI/CD configs and what they do
• Deployment targets

14. Risk & Debt (Top-Level)

Only project-wide risks here. Module-specific risks go in module deep dives.

Category	Finding	Location	Severity

---

L1: Module Deep Dive (module-name/_overview.md)

One file per top-level module. Analyzes the module as if it were its own small project.

L1 Sections

1. Module Card

Module:             [name]
Source:             [path]
Owner/Team:        [if identifiable from CODEOWNERS, git blame]
Language(s):        [if different from project]
Lines of Code:     [via cloc or wc -l]
Test Files:         [n] / Source Files: [n]
Depends On:        [list of internal modules]
Depended By:       [list of internal modules that import this]

2. Purpose & Boundaries

• What this module does (2-3 sentences)
• What this module does NOT do (explicit scope boundary)
• Key domain concepts it owns

3. Public API

What this module exports to the rest of the codebase:

Export	Type	Used By	Location
authenticate()	function	routes/, middleware/	src/auth/index.ts:42
User	type	core/, admin/	src/auth/types.ts:10

4. Internal Structure

Sub-module inventory (if this module has internal structure):

Sub-module	Path	Responsibility	LOC	Deep Dive
strategies	src/auth/strategies/	OAuth, JWT, SAML providers	800	→ detail
middleware	src/auth/middleware/	Express middleware for route protection	150	(inline below)

If a sub-module is simple (< 5 files), document inline instead of creating L2.

5. Key Code Paths

Trace 1-2 representative flows through THIS module:

Request: POST /login
→ routes/auth.ts:handleLogin()
  → services/auth.ts:authenticate(credentials)
    → strategies/local.ts:verify(email, password)
      → repositories/user.ts:findByEmail(email)
        → DB query
    → services/token.ts:generateJWT(user)
  → Response: { token, user }

6. Data Models (owned by this module)

Model	Fields	Relationships	Storage
User	id, email, passwordHash, role	has-many Sessions	PostgreSQL users table

7. Concurrency (if applicable)

How does THIS module handle concurrent access? Locks, queues, worker pools, rate limiters? Skip if the module is purely synchronous/stateless.

8. Error Handling (module-level)

• What errors can this module produce?
• How does it communicate errors to callers?
• Are there unhandled edge cases?

9. Internal Dependency Graph

Mermaid diagram of sub-modules within this module.

10. Module-Specific Risks

Risk	Location	Severity

---

L2: Sub-Module Deep Dive (module/sub-module/_overview.md)

Only create when a sub-module has >= 3 files with non-trivial logic. Uses same structure as L1 but:

• No further nesting (document everything inline)
• "Internal Structure" section lists files directly instead of sub-directories
• Shorter — typically 50-100 lines

L2 Sections

1. Module Card (same as L1)
2. Purpose & Boundaries (same)
3. Public API → Exports (what parent module uses from here)
4. Internal Structure → File Inventory:

File	Responsibility	Key Exports	LOC
local.ts	Email/password authentication	verify(), register()	120
oauth.ts	OAuth2 flow	initiateOAuth(), handleCallback()	210
jwt.ts	Token generation & validation	sign(), verify(), decode()	85

5. Key Code Paths (same)
6. Data Models (same, if any)
7. Concurrency (same — skip if purely synchronous)
8. Error Handling (same)
9. Risks (same)

---

L0: Global Dependency Graph (_dependency-graph.md)

Dedicated file for the full inter-module dependency diagram when the graph is complex.

Content

1. Full Mermaid diagram — all modules as nodes, imports as edges
2. Layered view — group modules by architectural layer:

graph TD
    subgraph "Entry Layer"
        API[api]
        CLI[cli]
    end
    subgraph "Application Layer"
        Auth[auth]
        Payments[payments]
        Orders[orders]
    end
    subgraph "Domain Layer"
        Core[core]
        Models[models]
    end
    subgraph "Infrastructure"
        DB[database]
        Cache[cache]
        Queue[queue]
    end

    API --> Auth
    API --> Orders
    CLI --> Orders
    Auth --> Core
    Payments --> Core
    Payments --> Queue
    Orders --> Core
    Orders --> Payments
    Core --> Models
    DB --> Models
    Cache --> Models

3. Analysis:

   • Circular dependencies (list exact import chains)
   • Layer violations (inner depending on outer)
   • Hub modules (high fan-in)
   • Fragile modules (high fan-out)

4. Dependency matrix (for 8+ modules):

↓ uses →	core	auth	payments	orders	db
api	✓	✓		✓
auth	✓				✓
payments	✓				✓
orders	✓		✓		✓

---

L0: External Systems Integration (_integrations.md)

Dedicated file mapping all external system boundaries.

Content

System Map (Mermaid):

graph LR
    subgraph "This System"
        App[Application]
    end

    App -- "PostgreSQL\nport 5432\nconnection pool: 20" --> DB[(PostgreSQL)]
    App -- "Redis\nport 6379\nTTL: 300s" --> Cache[(Redis)]
    App -- "AMQP\nretry: 3x" --> MQ[RabbitMQ]
    App -- "HTTPS\nOAuth2\ntimeout: 5s" --> Stripe[Stripe API]
    App -- "HTTPS\nAPI key\ntimeout: 10s" --> SendGrid[SendGrid]
    App -- "S3 protocol\nIAM role" --> S3[AWS S3]

Integration Inventory:

External System	Protocol	Auth Method	Timeout	Retry	Circuit Breaker?	Config Location
PostgreSQL	TCP/5432	connection string	pool: 30s	reconnect: 3x	No	src/config/db.ts
Stripe API	HTTPS	OAuth2 Bearer	5s	3x exponential	Yes	src/payments/stripe.ts
Redis	TCP/6379	password	1s	No	No	src/config/cache.ts

Analysis:

• Which integrations lack timeout configuration?
• Which lack retry/circuit-breaker patterns?
• Are credentials properly externalized (env vars, secrets manager) or hardcoded?
• Single points of failure: what happens if each external system goes down?

---

L0: Evolution (_evolution.md)

When comparing two versions. Skip if no version comparison requested.

Sections

Change Scope

Compared:       [v1.0.0 → v2.0.0]
Commits:        [n]
Files Changed:  [n]
Insertions:     [n]  Deletions: [n]

How to gather: git diff <old>..<new> --stat, git log <old>..<new> --oneline

Structural Changes

Change Type	Before	After	Path(s)
Module added	—	payments/	src/payments/
Module removed	legacy-auth/	—	src/legacy-auth/
Module renamed	utils/	shared/	src/shared/
Module split	core/	core/ + domain/	src/core/, src/domain/
Module merged	a/ + b/	ab/	src/ab/

Dependency Graph Diff

One Mermaid diff diagram with color coding:

graph LR
    classDef added fill:#2d6,stroke:#fff
    classDef removed fill:#d33,stroke:#fff
    classDef changed fill:#fc3,stroke:#fff

    A --> B
    A --> C:::added
    A -.-> D:::removed
    B:::changed --> E

Analysis: new deps, removed deps, direction changes, new cycles.

Architecture & Design Shifts

Dimension	Before	After	Evidence
Architecture style	Monolith	Modular monolith	src/modules/ introduced
Error handling	Exceptions	Result types	Result<T,E> in src/core/types.ts
State management	Redux	Zustand	package.json diff
API style	REST	GraphQL	src/graphql/ added

For each: what changed, why (infer from commits/comments), impact on maintainability.

API Surface Changes

Change	Endpoint / Export	Before	After	Breaking?

List all breaking changes explicitly.

Data Model Migration

Entity	Change	Before	After	Migration Exists?

Risk Delta

New risks introduced + Resolved risks from previous version.

Evolution Summary

Direction:        [e.g., "Monolith → Modular, REST → GraphQL"]
Breaking Changes: [n]
New Modules:      [list]
Removed Modules:  [list]
Key Shift:        [one-line]
Top New Risk:     [one-line]
Top Resolved:     [one-line]

---

Execution Checklist

FULL mode

1. Scale assessment — decide SINGLE-FILE or MULTI-FILE
2. Check for prior analysis — if output dir exists, enter incremental update mode
3. Create output directory — docs/architecture/ or user-specified path
4. Write L0 _overview.md FIRST — this forces you to understand the whole before the parts
5. Write L0 _dependency-graph.md — global dependency map
6. Write L0 _integrations.md — external systems map
7. Write L1 per module — one _overview.md per top-level module
8. Write L2 where needed — only for complex sub-modules (>= 3 files with logic)
9. Write L0 _evolution.md — only if version comparison requested
10. Verify all nav links — every Parent/Children/Source link must resolve
11. Add analysis footer — <!-- Last analyzed: <commit-hash> <date> --> to each file

FOCUS mode

1. Create module directory — docs/architecture/<module-name>/
2. Write Context section — where this module sits in the larger system (Mermaid highlight)
3. Write _overview.md — using L1 template
4. Write L2 where needed — for complex sub-modules within this module
5. Add analysis footer

DIFF mode

1. Gather git diff data — git diff, git log, git diff --stat
2. Write or append to _evolution.md
3. Regenerate L1 docs for modules with significant changes (optional)
4. Update L0 _overview.md if module inventory or dependency graph changed

Common Mistakes

Mistake	Fix
Everything in one giant file	Use MULTI-FILE for >= 4 modules
Full re-analysis when only 2 files changed	Use incremental update mode
Generic observations without file paths	Every claim needs a concrete citation
Fabricating modules that don't exist	Say "Unable to determine" when unsure
Flat module list without hierarchy	Recurse into sub-modules at L1 and L2
Missing data flow description	Trace at least 1 real request end-to-end per level
Skipping sections	All sections required; mark N/A with reason
L1 doc repeating L0 content verbatim	L0 = one-line summary per module; L1 = full deep dive
Creating L2 for trivial sub-modules	Only when >= 3 files with non-trivial logic
Broken nav links between docs	Verify every link after writing all files
Listing file diffs without explaining WHY	Always infer motivation from commits/comments
Missing breaking change identification	Explicitly flag every API/schema breaking change
"Good error handling" without tracing a path	Trace at least 1 error from origin to user response
"Uses async/await" without analyzing concurrency	Identify shared state, locks, race condition risks
Listing frameworks without assessing idiom usage	Evaluate actual code against framework best practices
Analyzing entire monorepo when user asked about one package	Respect scope — use FOCUS mode