Deep Dive Analysis

# AI-Powered Code Analysis Methodology

> This document defines how Claude should semantically analyze source code beyond mechanical AST extraction.

---

## Core Principle: Understanding Over Extraction

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                         THE SEMANTIC ANALYSIS MANDATE                        ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  Scripts extract STRUCTURE:  "This file has class Foo with method bar()"    ║
║  Claude extracts MEANING:    "Foo implements the Repository pattern for     ║
║                               caching user sessions with TTL expiration"    ║
║                                                                              ║
║  NEVER stop at structure. ALWAYS pursue understanding.                      ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

---

## The Five Layers of Code Understanding

### Layer 1: WHAT (Structural) - Scripts handle this
- Classes, functions, imports
- Line counts, dependencies
- AST-extractable information

### Layer 2: HOW (Mechanical) - Claude's first pass
- Algorithm implementation details
- Data flow through functions
- State transformations

### Layer 3: WHY (Intent) - Claude's deep analysis
- Business purpose of the code
- Problem being solved
- Design decisions made

### Layer 4: WHEN (Temporal) - Claude's behavioral analysis
- Execution conditions and triggers
- Lifecycle and state transitions
- Concurrency and timing

### Layer 5: CONSEQUENCES (Impact) - Claude's systems thinking
- Side effects and mutations
- Downstream dependencies
- Failure modes and edge cases

---

## Semantic Analysis Questions

When analyzing ANY code unit, Claude must answer these questions:

### Identity Questions
```
□ What is this code's single responsibility?
□ What abstraction does it represent?
□ What would break if this code didn't exist?
```

### Behavior Questions
```
□ What are ALL possible inputs?
□ What are ALL possible outputs (including side effects)?
□ What state does it read? What state does it mutate?
□ What are the preconditions for correct operation?
□ What are the postconditions guaranteed after execution?
```

### Integration Questions
```
□ Who calls this code? Under what circumstances?
□ What does this code call? Why those specific dependencies?
□ What contracts/interfaces does it fulfill?
□ What would need to change if this code's signature changed?
```

### Quality Questions
```
□ What could go wrong? How is failure handled?
□ Are there implicit assumptions that could break?
□ Is there hidden coupling to global state or external systems?
□ Are there race conditions or timing dependencies?
```

---

## Analysis Patterns by Code Type

### Pattern: Service/Manager Class
```
RECOGNIZE BY:
- Name ends in Service, Manager, Handler, Controller
- Has multiple public methods
- Coordinates between other components

ANALYZE FOR:
1. What domain concept does this service own?
2. What operations does it expose? (CRUD? Commands? Queries?)
3. What resources does it manage? (connections, state, caches)
4. What is the lifecycle? (singleton? per-request? pooled?)
5. What are the thread-safety guarantees?

DOCUMENT:
- Primary responsibility (one sentence)
- Key operations with preconditions
- Resource management strategy
- Error handling approach
- Integration points
```

### Pattern: Data Model/Entity
```
RECOGNIZE BY:
- Name is a noun (User, Order, Transaction)
- Primarily contains fields/attributes
- May have validation logic

ANALYZE FOR:
1. What real-world concept does this represent?
2. What are the invariants? (fields that must always be valid)
3. What are the valid state transitions?
4. What is the identity? (which fields make it unique)
5. What are the relationships t