code-explainer

name	code-explainer
description	Explain and analyze source code for learning. Auto-detects prerequisite knowledge and creates docs before explaining. Use when asked to explain, analyze, break down, or teach code.

Code Explainer

Create comprehensive, beginner-friendly code explanations that include foundational knowledge, line-by-line annotations, analogies, ASCII diagrams, and FAQ sections.

---

When to Use This Skill

• User asks to explain, analyze, or document code for learning
• User wants to understand a new codebase or unfamiliar script
• Creating educational documentation for a project
• Onboarding material for new developers joining a project
• User says "I don't understand this code" or "what does this do"

When NOT to Use This Skill

• User wants API reference docs → use a doc-generation tool instead
• User wants to refactor or fix code → just do the refactoring
• User only needs a one-line summary → answer directly, don't create full docs

---

Core Rules

1. English only — All output documents must be in English
2. Analogies first — Every complex concept MUST have a real-world analogy
3. Progressive depth — Start simple, then go deeper. Never assume prior knowledge
4. Show, don't just tell — Use ASCII diagrams, code examples, tables for comparison
5. Language-agnostic — This skill works for ANY programming language or framework
6. Foundational knowledge auto-detect — If the code uses domain-specific concepts (DL, web frameworks, databases, DevOps, etc.), create a prerequisite knowledge doc FIRST

---

Workflow

Step 1 — Survey the Code

Read the code and determine:

• Language & framework (Python + PyTorch? TypeScript + Next.js? Go + gRPC?)
• Domain (Machine Learning? Web? Systems? Data pipeline? DevOps?)
• Complexity level — Does the reader need foundational knowledge?
• Key concepts — List every concept a beginner would NOT know

Example survey output (internal, not in final doc):

  Language: Python
  Framework: Ultralytics (YOLO), PyTorch
  Domain: Deep Learning — Object Detection
  Foundational knowledge needed: YES
  Key concepts: transfer learning, GPU/CUDA, loss functions,
                hyperparameters, bounding boxes, epochs, batch size

Step 2 — Create Foundational Knowledge Doc (if needed)

If Step 1 identifies domain-specific concepts, create 00_foundational_knowledge.md BEFORE explaining any code.

When to create this doc:

• Code uses specialized libraries (PyTorch, TensorFlow, React, Kubernetes, etc.)
• Domain has jargon a general developer wouldn't know
• Multiple scripts share common concepts → explain once, reference everywhere

Structure of the foundational knowledge doc:

# 🧠 Foundational Knowledge — Read Before Starting

> **Goal:** Understand the core concepts needed to read the code in this project.
> If you already know [DOMAIN], you can skip this file.

---

## 1. [High-Level Concept]

[Analogy] + [Simple explanation] + [Why it matters for this project]

## 2. [Next Concept]

...

## N. Key Terminology

| Term | Explanation | Analogy |
| ---- | ----------- | ------- |
| ...  | ...         | ...     |

## Project Flow Summary

[ASCII diagram showing how all scripts connect]

For the full template, see references/output-template.md

Step 3 — Explain the Code

For each code file, create a documentation file following this structure:

# 📄 File: `filename.py` — [One-line purpose]

> **Goal:** [What the reader will understand after reading this doc]

---

## 📋 Original Code (Annotated)

\`\`\`python

# — SECTION NAME —

code_line_here # Inline comment explaining what this does
\`\`\`

---

## 🧩 Detailed Explanation

### [Concept 1 from the code]

[Analogy] → [Technical explanation] → [ASCII diagram if applicable]

### [Concept 2]

...

---

## 📝 Language Syntax Explained

### `some_syntax_here`

\`\`\`python

# What it does + example

\`\`\`

---

## ❓ FAQ

**Q: [Common question]**
A: [Clear answer]

---

> **Next:** [link to next file]

Step 4 — Create README Index

If multiple files are documented, create/update a README.md index:

# 📚 Code Documentation

## Table of Contents

| #   | File                                | Content       |
| --- | ----------------------------------- | ------------- |
| 0   | [00_foundational_knowledge.md](...) | Prerequisites |
| 1   | [01_filename.md](...)               | [Description] |
| ... | ...                                 | ...           |

## Reading Order

[ASCII flow showing dependencies]

---

Analogy Writing Guide

Good analogies are the most important part of this skill. Rules:

Rule	Example
Use everyday objects	"A batch is like a teacher grading 8 papers at once"
Match complexity	Don't use a PhD analogy for a simple concept
Be consistent	If you compare training to studying, keep that metaphor
Use tables for comparisons	CPU vs GPU, SQL vs NoSQL, etc.

Good Analogy

Learning Rate = the "step size" each time the model updates its knowledge

  Too large (0.1):  Jumping wildly — never converges!
  Just right (0.005): Steady descent — converges well
  Too small (0.00001): Standing still — takes forever!

Bad Analogy

Learning rate is a hyperparameter that controls the step size
during gradient descent optimization.

(Too technical, no analogy, no visual — useless for beginners)

---

ASCII Diagram Guide

Use ASCII diagrams for:

• Data flow between scripts/components
• Architecture of systems or models
• Comparisons (before/after, good/bad)
• Visual math (coordinates, grids, layouts)

Example — Data pipeline flow:

  Raw Data → Clean → Split → Train → Evaluate → Deploy
  ┌──────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌────────┐  ┌──────┐
  │ CSV  │→ │Clean│→ │Split│→ │Train│→ │Evaluate│→ │Deploy│
  │ JSON │  │ NaN │  │70/30│  │Model│  │Metrics │  │ API  │
  └──────┘  └─────┘  └─────┘  └─────┘  └────────┘  └──────┘

---

Anti-Patterns (Avoid)

❌ Don't	✅ Do Instead
Explain only WHAT code does	Explain WHY + WHEN + HOW
Skip library/framework context	Explain what the library is and why it's used
Write walls of text	Use tables, diagrams, code blocks
Assume the reader knows jargon	Define every term with an analogy
Copy-paste official docs	Rewrite in beginner-friendly language
Hard-code for one language	Keep patterns language-agnostic
Write foundational knowledge inside code docs	Separate into 00_foundational_knowledge.md

---

Output File Naming Convention

docs/
├── README.md                        ← Index + reading order
├── 00_foundational_knowledge.md     ← Domain prerequisites (if needed)
├── 01_[script_name].md              ← First script explanation
├── 02_[script_name].md              ← Second script
└── ...

For full output templates with examples, see references/output-template.md For foundational knowledge patterns by domain, see references/knowledge-patterns.md