Code Explanation & Analysis

Expert at explaining complex code through clear narratives, diagrams, and step-by-step breakdowns for developers at all levels.

When to Use

• Explaining complex code, algorithms, or system behavior

• Creating onboarding walkthroughs or learning materials

• Producing step-by-step breakdowns with diagrams

• Teaching design patterns or debugging reasoning

When NOT to Use

• Implementing new features or refactoring (use coding skills)

• Writing API docs or user documentation (use doc-generate)

• No code or design to analyze

Explanation Framework

Step 1: High-Level Summary

Start with the "what" and "why" before diving into "how."

What This Does

[One sentence: purpose and context]

Why It Exists

[The problem it solves or requirement it fulfills]

How It Works (Overview)

[2-3 sentence summary of the approach]

Step 2: Architecture Map

Show the big picture with ASCII diagrams or Mermaid:

Input → [Parser] → AST → [Transformer] → IR → [Generator] → Output ↓ [Validator] ↓ Error Reports

Step 3: Walk Through Key Components

For each component:

• Purpose — What role it plays

• Inputs/Outputs — What goes in, what comes out

• Key Logic — The core algorithm or decision point

• Edge Cases — What could go wrong

Step 4: Annotated Code Walkthrough

STEP 1: Parse the document into pages

pages = re.split(r"--- Page \d+ ---\n?", raw_text)

Why: Each page may contain different form sections.

The regex matches the page delimiter inserted by ingestion.

STEP 2: Extract fields per page

for i, page in enumerate(pages): fields = extract_fields(page, schema) # Why: Per-page extraction prevents cross-page hallucination. # The schema constrains what fields are valid.

Step 5: Pitfalls & Edge Cases

Scenario What Happens Why

Empty input Returns []

Guard clause at line 12

Malformed JSON Raises ValueError

Strict parsing mode

Concurrent access Thread-safe via lock threading.Lock at line 5

Explanation Patterns

Pattern 1: Top-Down (Recommended for Systems)

• System purpose and boundaries

• Major components and their relationships

• Data flow between components

• Deep dive into each component

• Cross-cutting concerns (error handling, logging)

Pattern 2: Bottom-Up (Recommended for Algorithms)

• Core data structures

• Basic operations on those structures

• How operations compose into the algorithm

• Complexity analysis (time and space)

• Optimization techniques used

Pattern 3: Trace-Through (Recommended for Debugging)

• Pick a concrete input

• Trace execution step by step

• Show state at each decision point

• Highlight where behavior diverges from expectation

• Identify the root cause

Diagram Types

Type Use For Tool

Flowchart Control flow, decisions Mermaid flowchart

Sequence API calls, message passing Mermaid sequenceDiagram

Class/ER Data models, relationships Mermaid classDiagram

ASCII Quick inline diagrams Plain text

State State machines, lifecycles Mermaid stateDiagram

Quality Checklist

• High-level summary comes before details

• Diagram shows component relationships

• Key decision points are explained (the "why")

• Edge cases and error paths are covered

• Code annotations reference specific line numbers

• Complexity analysis included for algorithms

• Reader can follow without running the code