patch-explainer

# 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