# Code Analysis Framework

This reference provides a structured approach for deeply analyzing code, whether examining changes (patches/diffs) or understanding existing code (classes, subsystems, repositories).

## Analysis Dimensions

Every code analysis should address these dimensions:

### 1. Purpose & Context
- **What**: What does this code do?
- **Why it exists**: What problem does it solve?
- **Where it fits**: How does it relate to surrounding components?

### 2. Structure & Organization
- **Components**: What are the key pieces?
- **Relationships**: How do components interact?
- **Hierarchy**: What are the layers/abstractions?

### 3. Behavior & Flow
- **Data flow**: How does data move through the system?
- **Control flow**: What is the execution path?
- **State transitions**: What states exist and how do they change?

### 4. Assumptions & Invariants
- **Preconditions**: What must be true before execution?
- **Postconditions**: What must be true after execution?
- **Invariants**: What must always be true?

### 5. Failure Modes & Edge Cases
- **What could go wrong**: Identify failure points
- **Error handling**: How are failures managed?
- **Edge cases**: Boundary conditions and corner cases

### 6. Concurrency & Timing
- **Threading model**: Single-threaded, multi-threaded, async?
- **Synchronization**: Locks, atomics, message passing?
- **Race conditions**: Potential data races or ordering issues?
- **Deadlocks**: Circular dependencies in locking?

## Analysis Process for Patches/Diffs

When analyzing changes (git diff, patch file, PR):

### Step 1: Identify the Change Type
Categorize the change:
- **Bug fix**: Correcting incorrect behavior
- **Feature addition**: New functionality
- **Refactoring**: Restructuring without behavior change
- **Performance optimization**: Improving efficiency
- **Technical debt**: Cleanup, documentation, tests

### Step 2: Understand the Before State
- What was the old behavior?
- What was the problem with the old code?
- What assumptions did the old code make?

### Step 3: Understand the After State
- What is the new behavior?
- How does it differ from the old behavior?
- What new assumptions are introduced?

### Step 4: Analyze the Transition
- **Why this change**: What problem does it solve?
- **How it works**: Mechanism of the change
- **Critical modifications**: Which changes are most important?
- **Side effects**: What else is affected?

### Step 5: Visualize Before/After
Create ASCII diagrams showing:
- State transitions (before vs after)
- Data flow changes
- Control flow modifications
- Component relationship changes

### Step 6: Deep Reasoning
For each significant change, ask:
- **Correctness**: Is this change correct?
- **Completeness**: Does it fully solve the problem?
- **Safety**: Does it introduce new issues?
- **Assumptions**: What must be true for this to work?
- **Failure modes**: What could go wrong?

## Analysis Process for Existing Code

When analyzing existing code (class, subsystem, repository):

### Step 1: Identify Purpose
- What is this code responsible for?
- Why does it exist?
- What problem domain does it address?

### Step 2: Map the Structure
Create hierarchy diagram showing:
- Main components/classes
- Package/module organization
- Key abstractions
- Dependency relationships

### Step 3: Trace Key Workflows
Identify and trace 2-3 most important workflows:
- Entry points
- Step-by-step execution
- Data transformations
- Exit points/results

### Step 4: Identify State & Transitions
- What state does this code manage?
- How does state change over time?
- What are the valid state transitions?
- What triggers transitions?

### Step 5: Analyze Interactions
- How do components communicate?
- What are the interfaces/APIs?
- Message passing patterns
- Synchronous vs asynchronous calls

### Step 6: Deep Reasoning
For critical paths:
- **Invariants**: What must always be true?
- **Assumptions**: What does the code assume?
- **Concurrency**: How does it handle concurrent access?
- **Failure handling**: How are errors managed?
- **Edge cases**: What are the boundary conditions?

## Levels of Granularity

Adjust depth based on scope:

### Single Function/Method
- Purpose and return value
- Parameter requirements
- Side effects
- Key algorithm steps
- Error conditions

### Single Class
- Responsibility (what it does)
- State (fields/properties)
- Key methods and their relationships
- Lifecycle (creation → use → cleanup)
- Invariants maintained

### Subsystem (Multiple Classes)
- High-level purpose
- Component breakdown
- Interface boundaries
- Main workflows (2-3 key scenarios)
- Inter-component communication

### Repository (Full Codebase)
- Architecture overview (layers/modules)
- Core abstractions
- Key subsystems and their roles
- Major data flows
- Critical patterns used throughout

## Concurrency Analysis Checklist

When analyzing concurrent code:

### Data Race Detection
-  Identify all shared mutable state
-  Check for unsynchronized access
-  Verify read/write ordering
-  Look for missing memory barriers

### Deadlock Detection
-  Identify all lock acquisitions
-  Check for lock ordering violations
-  Look for circular dependencies
-  Verify timeout mechanisms

### Thread Safety Patterns
-  Immutability: Are objects immutable?
-  Synchronization: Are critical sections protected?
-  Lock-free: Are atomic operations used correctly?
-  Thread-local: Is state properly isolated?
-  Message passing: Are channels/queues used safely?

### Async/Await Analysis
-  Understand execution context switches
-  Identify blocking operations in async code
-  Check for proper error propagation
-  Verify cancellation handling

## Assumption Identification Patterns

Look for implicit assumptions in:

### Ordering Assumptions
```
// Assumes operation A completes before B
operationA();
operationB(); // Depends on A's results
```

### Null/Validity Assumptions
```
// Assumes value is never null
value.method(); // No null check
```

### State Assumptions
```
// Assumes object is in specific state
process(); // Requires initialization first
```

### Concurrency Assumptions
```
// Assumes single-threaded access
counter++; // Not atomic
```

### Resource Assumptions
```
// Assumes resource is available
file.write(data); // Doesn't check for full disk
```

## Failure Mode Identification

Common failure patterns:

### Resource Exhaustion
- Memory leaks
- File descriptor leaks
- Thread pool exhaustion
- Connection pool exhaustion

### Timing Issues
- Race conditions
- Deadlocks
- Timeouts not handled
- Retry storms

### Data Issues
- Null pointer exceptions
- Array/buffer overflows
- Type mismatches
- Encoding issues

### Error Propagation
- Exceptions swallowed
- Errors not logged
- Inconsistent error states
- Missing rollback logic

### External Dependencies
- Network failures
- Database unavailability
- Third-party API changes
- Configuration errors

## Visualization Guidelines

### When to Use Each Diagram Type

**State Machine**: When analyzing:
- Status/state fields that change
- Lifecycle of objects
- Protocol state machines
- Transaction states

**Data Flow**: When analyzing:
- Information transformation
- Pipeline processing
- Request/response patterns
- Data dependencies

**Sequence Diagram**: When analyzing:
- Component interactions
- Message protocols
- API call sequences
- Distributed system operations

**Component Diagram**: When analyzing:
- System architecture
- Module relationships
- Layer separation
- Dependency structure

**Before/After**: When analyzing:
- Code changes/patches
- Refactoring
- Bug fixes
- Architecture evolution

### Diagram Complexity Guidelines

**Simple (1-5 elements)**: Show core concept clearly
**Medium (6-15 elements)**: Show main flow with key branches
**Complex (16+ elements)**: Break into multiple focused diagrams

Prefer multiple simple diagrams over one complex diagram.

## Communication Strategy

### Structure Your Explanation

1. **Executive Summary** (1-2 paragraphs)
   - What this code does
   - Why it exists
   - Key insight in one sentence

2. **Visual Overview** (ASCII diagram)
   - High-level structure or flow
   - Main components/states
   - Critical paths highlighted

3. **Detailed Analysis** (organized by aspect)
   - Purpose & behavior
   - Structure & components
   - Assumptions & invariants
   - Failure modes

4. **Critical Insights** (bullet points)
   - Most important findings
   - Potential issues found
   - Recommendations if applicable

### Prioritization

Focus on:
- **High impact**: Changes to critical paths
- **High risk**: Concurrency, error handling, resource management
- **High complexity**: Tricky algorithms, subtle interactions
- **High value**: Key abstractions, main workflows

Skip or minimize:
- Boilerplate code
- Obvious getters/setters
- Standard patterns done correctly
- Low-risk refactoring

## Example Analysis Template

```
# Analysis of [Component/Patch Name]

## Summary
[2-3 sentences: what it is, what it does, why it matters]

## High-Level Structure
[ASCII diagram showing main components/flow]

## Key Behaviors
### Workflow 1: [Name]
[Sequence diagram or flow diagram]
- Step 1: ...
- Step 2: ...

### Workflow 2: [Name]
[Sequence diagram or flow diagram]

## State Management
[State machine diagram if applicable]

## Critical Assumptions
1. **[Assumption]**: [Explanation]
   - Why: [Why this assumption exists]
   - Risk: [What breaks if invalid]

2. **[Assumption]**: ...

## Failure Modes
1. **[Failure scenario]**: [Description]
   - Trigger: [What causes it]
   - Impact: [What goes wrong]
   - Mitigation: [How it's handled or should be]

2. **[Failure scenario]**: ...

## Concurrency Analysis (if applicable)
[Thread interaction diagram]
- Shared state: [What's shared]
- Synchronization: [How it's protected]
- Risks: [Potential races/deadlocks]

## Before/After (for patches only)
### Before
[Diagram of old behavior]

### After
[Diagram of new behavior]

### Why This Change
[Explanation of the improvement]

## Key Insights
- [Most important finding 1]
- [Most important finding 2]
- [Most important finding 3]
```
