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 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 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