patch-explainer

---
name: patch-explainer
version: "1.0.0"
description: Deep code analysis with ASCII visualizations showing structure, flow, and state transitions. Use when analyzing patches/diffs, explaining classes or subsystems, understanding code architecture, reviewing changes for inconsistencies, or when asked to visualize how code works. Provides before/after diagrams, data/control flow, concurrency analysis, assumptions, and failure modes. Triggers on explain this patch/code/class, how does X work, show me the flow, visualize this change, code review requests, or proactive analysis during PR reviews.
---

# Patch Explainer

Deeply analyze and visualize code using ASCII diagrams to reveal structure, behavior, and interactions.

## What This Skill Does

Provides comprehensive code analysis with rich ASCII visualizations for:
- **Patches/diffs**: Before/after states, what changed and why
- **Classes**: Purpose, structure, state transitions, workflows
- **Subsystems**: Component interactions, data flow, architecture
- **Repositories**: Overall structure, key abstractions, major patterns
- **Code reviews**: Finding inconsistencies, analyzing assumptions and failure modes

## Analysis Approach

### For Any Code (Patches, Classes, Subsystems, Repositories)

1. **Identify the core purpose** - What does this code do and why does it exist?

2. **Create ASCII visualizations** showing:
   - Structure (components, layers, dependencies)
   - Behavior (data flow, control flow, state transitions)
   - Interactions (sequence diagrams, message passing, concurrency)
   - For patches: before/after comparisons

3. **Deep reasoning** about:
   - **Assumptions**: What must be true for this to work correctly?
   - **Failure modes**: What could go wrong at each step?
   - **Concurrency**: If multiple threads/processes, show their interactions
   - **Invariants**: What must always hold true?

4. **Focus on the "why"**:
   - Why does this code exist?
   - Why was this approach chosen?
   - For changes: Why this modification? What problem does it solve?

### Visualization Strategy

Choose diagram types based on what you're explaining:

**State machines** - When code manages states/status:
```
[Initial] --event--> [Processing] --success--> [Complete]
                          |
                       failure
                          |
                          v
                      [Failed]
```

**Data flow** - When showing information movement:
```
Input → [Transform A] → [Transform B] → Output
```

**Sequence diagrams** - When showing component interactions:
```
Client          Server          Database
  |               |                 |
  |--request----->|                 |
  |               |----query------->|
  |               |<---result-------|
  |<--response----|                 |
```

**Component structure** - When showing architecture:
```
┌─────────────────────┐
│   Application       │
└──────────┬──────────┘
           |
┌──────────┴──────────┐
│   Service Layer     │
└──────────┬──────────┘
           |
┌──────────┴──────────┐
│   Data Layer        │
└─────────────────────┘
```

**Before/after** - When explaining changes:
```
BEFORE                  AFTER
─────────────────────────────────
[A] → [B] → [C]        [A] → [Cache?] ─Yes→ [C]
                              |
                              No
                              v
                            [B] → [C]
```

### Reference Materials

**ASCII diagram templates**: See [ascii_patterns.md](references/ascii_patterns.md) for:
- State machine patterns
- Data flow diagrams
- Sequence diagrams
- Component/architecture diagrams
- Before/after comparisons
- Concurrency patterns
- Control flow patterns
- Dependency graphs

**Analysis methodology**: See [analysis_framework.md](references/analysis_framework.md) for:
- Structured analysis process for patches vs existing code
- Concurrency analysis checklist
- Assumption identification patterns
- Failure mode identification
- Analysis depth guidelines by scope (function → class → subsystem → repository)

## Analysis Workflow

### For Patches/Diffs

1. Read the patch to understand what changed
2. Identify the change type (bug fix, feature, refactor, optimization)
3. Create before/after ASCII diagrams showing:
   - Old behavior vs new behavior
   - State transitions that changed
   - Data flow modifications
4. Explain what fundamentally changed:
   - What problem did the old code have?
   - How does the new code solve it?
   - What assumptions changed?
5. Analyze failure modes:
   - What could go wrong with this change?
   - Are there edge cases not handled?
   - Concurrency implications?
6. Focus on the "why": What problem does each modification solve?

### For Classes

1. Read the class to understand its purpose
2. Create ASCII diagram showing:
   - Class structure (key fields/methods)
   - State machine if it manages state
   - How it fits with related classes
3. Explain key workflows (2-3 most important methods)
4. Identify assumptions and invariants
5. Analyze failure modes and edge cases
6. Focus on the "why": Why does this class exist? What problem does it solve?

### For Subsystems

1. Identify the components in the subsystem
2. Create ASCII diagram showing:
   - Component relationships
   - Key interfaces/boundaries
   - Main data flows
3. Trace 2-3 key workflows through the subsystem
4. Explain how components interact
5. Identify assumptions across component boundaries
6. Focus on the "why": What is this subsystem's role in the larger system?

### For Repositories

1. Understand the high-level architecture
2. Create ASCII diagram showing:
   - Major modules/packages
   - Layered architecture
   - Key abstractions
3. Identify core workflows
4. Explain main patterns used throughout
5. Highlight critical subsystems
6. Focus on the "why": What problem does this codebase solve?

## Concurrency Analysis

When analyzing concurrent code, always show:

**Thread interactions**:
```
Thread A                State                Thread B
   |                      |                      |
   |--lock()------------>|                      |
   |                     [LOCKED]               |
   |--modify()---------->|                      |
   |--unlock()---------->|                      |
   |                     [UNLOCKED]             |
   |                      |<---------lock()-----|
   |                     [LOCKED]               |
```

**Race conditions**:
```
Thread A            Thread B
   |                   |
   |--read(x=10)      |
   |                   |--read(x=10)
   |--x=x+1           |
   |                   |--x=x+1
   |--write(x=11)     |
   |                   |--write(x=11)  ⚠ Lost update!

Result: x=11 (expected: x=12)
```

Check for:
- Shared mutable state without synchronization
- Lock ordering violations (potential deadlocks)
- Race conditions in read-modify-write operations
- Missing memory barriers

## Output Structure

Structure your analysis as:

### 1. Executive Summary
Brief overview (2-3 sentences) of what this code does and why it matters.

### 2. Visual Overview
High-level ASCII diagram showing the main structure or flow.

### 3. Detailed Analysis
Organized by aspect:
- **Purpose**: What it does and why it exists
- **Structure**: Components and their relationships
- **Key Workflows**: Step-by-step execution of main scenarios
- **State Management**: States and transitions (if applicable)
- **Assumptions**: What must be true for correctness
- **Failure Modes**: What could go wrong
- **Concurrency**: Thread safety analysis (if applicable)

### 4. For Patches: Before/After
- Before state (with diagram)
- After state (with diagram)
- Why this change was made
- Critical modifications explained

### 5. Key Insights
Bullet points highlighting:
- Most important findings
- Potential issues or risks
- Recommendations (if applicable)

## Prioritization

Focus on high-impact elements:
- **Critical paths**: Main workflows that matter most
- **High-risk code**: Concurrency, error handling, resource management
- **Complex logic**: Non-obvious algorithms or subtle interactions
- **Key abstractions**: Core interfaces and contracts

Minimize or skip:
- Boilerplate code
- Simple getters/setters
- Standard patterns done correctly
- Low-risk trivial changes

## Example Scenarios

**Scenario 1**: "Explain this patch"
→ Show before/after diagrams, explain what changed and why, analyze assumptions and failure modes

**Scenario 2**: "How does SafeCommandStore work?"
→ Show class structure, explain the exclusive access pattern, trace key methods, analyze thread safety

**Scenario 3**: "Explain the coordination subsystem"
→ Show component diagram, trace PreAccept→Accept→Commit flow, explain message passing, show quorum tracking

**Scenario 4**: "What's the architecture of this codebase?"
→ Show high-level module structure, identify key abstractions, explain main patterns, highlight critical subsystems

**Scenario 5**: During code review (proactive)
→ Analyze changes for inconsistencies, check assumptions, identify potential race conditions, verify error handling

More agent context in apache/cassandra

11 other files this repository gives its agents.