layered-first-principles-teaching

name	layered-first-principles-teaching
description	Use when explaining complex concepts to others, designing training materials, or preparing technical presentations with progressive disclosure
version	1
author	agent
tags	["teaching","learning","explanation"]

Layered First Principles Teaching

Overview

Transform complex concepts into progressive, first-principles explanations that build understanding layer by layer.

When to Use

Use when:

• You need to explain a complex concept to someone with less domain knowledge
• You're designing training materials, tutorials, or educational content
• You're preparing a technical presentation and need progressive disclosure
• A topic has multiple abstraction layers that require cognitive scaffolding
• You need to bridge the gap between intuitive understanding and technical depth

Don't use when:

• The concept is simple and doesn't benefit from layered decomposition
• You need quick reference documentation or a terse answer
• The audience already has deep expertise and only needs edge cases or implementation details

Quick Start

# Explain a concept progressively
kimi layered-first-principles-teaching "Explain blockchain"

# Target specific audience
kimi layered-first-principles-teaching "Explain transformers" --audience beginner

# Output to file
kimi layered-first-principles-teaching "Explain consensus algorithms" --output ./tutorial.md

Output Structure

Generated explanations contain 6 standard sections:

Section	Content	Purpose
Opening	One-sentence essence + intuitive analogy	Immediate understanding
First Principles	Problem essence, why existing solutions fail	Foundation building
Progressive Layers	3-4 layers from intuition to technical detail	Scaffolding learning
Analogies	Cross-domain comparisons	Relating to known concepts
Visualizations	ASCII diagrams, mental models	Spatial understanding
Summary	Key takeaways + further reading	Retention & next steps

Audience Levels

Level	Characteristics	Approach
Beginner	No prior knowledge	Heavy analogies, minimal jargon, focus on "why"
Intermediate	Some domain knowledge	Balance of intuition and technical detail
Expert	Deep domain knowledge	Focus on nuances, edge cases, implementation

Teaching Patterns

This skill uses progressive disclosure patterns from prompts/:

1. First Principles Analysis (first_principles.txt): Strip away abstractions, find root causes
2. Layered Decomposition (layered_decomposition.txt): Break into 3-4 cognitive layers
3. Analogy Generation (analogy_generation.txt): Find relatable comparisons
4. Visualization Design (visualization_design.txt): Create mental models and diagrams

Templates

Output templates in templates/ provide structure for:

• concept.md: General concept explanation
• algorithm.md: Algorithm walkthrough
• system.md: System architecture explanation

Examples

See examples/ for completed explanations:

• blockchain_explained.md: From "digital ledger" to Byzantine fault tolerance
• transformers_explained.md: From "pattern matching" to attention mechanisms

Workflow

When explaining a concept:

1. Load first principles prompt → Identify core problem and breakthrough insight
2. Load layered decomposition prompt → Structure into 3-4 cognitive layers
3. Load analogy generation prompt → Find 2-3 cross-domain analogies
4. Load visualization design prompt → Create ASCII diagrams and mental models
5. Apply appropriate template → Generate final explanation

Constraints

• Maximum 4 layers to avoid cognitive overload
• Each layer must build on previous without introducing new prerequisites
• Analogies must be familiar to target audience
• Visualizations should work in plain text (ASCII)