| 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)
-
Identify the core purpose - What does this code do and why does it exist?
-
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
-
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?
-
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
- Read the patch to understand what changed
- Identify the change type (bug fix, feature, refactor, optimization)
- Create before/after ASCII diagrams showing:
- Old behavior vs new behavior
- State transitions that changed
- Data flow modifications
- Explain what fundamentally changed:
- What problem did the old code have?
- How does the new code solve it?
- What assumptions changed?
- Analyze failure modes:
- What could go wrong with this change?
- Are there edge cases not handled?
- Concurrency implications?
- Focus on the "why": What problem does each modification solve?
For Classes
- Read the class to understand its purpose
- Create ASCII diagram showing:
- Class structure (key fields/methods)
- State machine if it manages state
- How it fits with related classes
- Explain key workflows (2-3 most important methods)
- Identify assumptions and invariants
- Analyze failure modes and edge cases
- Focus on the "why": Why does this class exist? What problem does it solve?
For Subsystems
- Identify the components in the subsystem
- Create ASCII diagram showing:
- Component relationships
- Key interfaces/boundaries
- Main data flows
- Trace 2-3 key workflows through the subsystem
- Explain how components interact
- Identify assumptions across component boundaries
- Focus on the "why": What is this subsystem's role in the larger system?
For Repositories
- Understand the high-level architecture
- Create ASCII diagram showing:
- Major modules/packages
- Layered architecture
- Key abstractions
- Identify core workflows
- Explain main patterns used throughout
- Highlight critical subsystems
- 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
