build-explanations

name	build-explanations
description	Teaching and information sharing across all contexts. Use when: writing docs, explaining concepts, making presentations, teaching in conversation, curating documentation, technical writing for impact, creating diagrams for explanation (Mermaid, D2, C4).

sensei-1337

Teaching is about understanding, not just explaining. Help students build mental models that stick.

The Purpose

Feynman's physics lectures work because he understood his students — their existing knowledge, their misconceptions, their cognitive limits. Simplicity was the result, not the goal.

Effective teaching requires:

• Understanding how your student processes information
• Adapting to their expertise level and role
• Structuring for their cognitive load
• Speaking in terms they already understand

The best explanation in the world fails if it doesn't match how the student learns.

Before Technique: Accuracy

All the rhetoric and structure in the world won't help if the content is wrong.

Why accuracy is foundational

Ethical:

• Teaching creates trust. Misrepresentation violates it.
• Learners form mental models from what you teach. Wrong models lead to wrong decisions.
• Misinformation compounds — learners pass it on, build on it, cite it.

Material:

• Decisions built on wrong foundations fail.
• Unlearning is harder than learning. Wrong first impressions persist.
• Credibility destroyed when errors discovered — everything else you taught becomes suspect.

Common accuracy failures

Failure	Example	Fix
Inference as finding	"Study shows X causes Y" when study showed correlation	State what was actually measured
Selective citation	Cherry-picking studies that support your view	Acknowledge contradictory evidence
Mechanism invention	"This works because..." when mechanism unknown	Say "correlates with" not "causes"
Implication overreach	Drawing conclusions the evidence doesn't support	Separate findings from interpretation
Framing bias	Presenting values as facts	Label philosophy as philosophy

The test

Before teaching anything:

1. What was actually found? — Not what you infer, what was measured
2. What's the evidence quality? — Sample size, methodology, replication
3. What are you adding? — Distinguish source claims from your interpretation
4. Would an honest skeptic accept this framing? — If not, revise

Teaching wrong things effectively is worse than not teaching at all.

See: accuracy-integrity

The Teaching Progression

Four stages, in order. Each builds on the last.

1. Reader Psychology → How do they process?

People scan, filter, and decide in milliseconds whether to engage. Understanding reader cognition:

• Cognitive load — working memory is limited; extraneous material harms learning (Mayer: d = 0.86 for coherence)
• Dual processing — readers use fast heuristics first; make the right path obvious
• Information foraging — readers follow "scent" of relevance; weak scent = bounce
• Processing fluency — easy-to-read feels more credible (Schwarz & Oppenheimer)

Different roles process differently:

• Decision-makers — scan for bottom line, ROI, risk (BLUF essential)
• Practitioners — seek "how to do X" (recipes, examples)
• Evaluators — assess credibility (methodology, sources)
• Learners — build mental models (scaffolding, progressive disclosure)

See: reader-psychology

2. Audience → Who are they?

Understand before you structure:

Question	Why it matters
What do they already believe?	You start from their map
What do they fear?	Resistance comes from fear
What do they value?	Connect to their concerns
What language do they speak?	Wrong words = "not for me"
What's their expertise level?	Novices need scaffolding; experts find it patronizing

Different audiences need different approaches. A decision-maker needs the bottom line in 30 seconds. A practitioner needs the recipe. An evaluator needs the evidence.

See: audience-empathy

3. Craft → How do you structure it?

Now choose structure and technique:

For	Use
Document type	Diataxis (tutorial, how-to, explanation, reference)
Information structure	BLUF, inverted pyramid
Managing complexity	Cognitive load theory, progressive disclosure
Testing understanding	Feynman technique
Collection organization	Single source of truth, linking architecture
Information organization	Where does content live? Findability, mental models

See references for each: diataxis, rhetoric-for-impact, cognitive-load, feynman-technique, collection-architecture, information-architecture

4. Translation → Speak their survival language

The same information, framed for different audiences:

The finding: AI tools may reduce productivity by 19%.

Audience	Translation
Decision-maker	"Your AI investment may be costing you 19% productivity. Here's the RCT and what to do."
Practitioner	"Here's research on when AI helps vs. hurts. Here's how to use it effectively."
Evaluator	"METR 2025 RCT: 19% slowdown vs. 24% perceived speedup. Methodology here."
Learner	"AI tools aren't automatically helpful. Let me show you when they work."

Same fact. Four different teachings. Each lands with its audience.

See: rhetoric-for-impact

Gauging Context

In conversation or when context is available, gauge the audience:

Expertise Signals

Signal	Likely level	Adjust
Uses jargon correctly	Competent+	Skip basics
Asks foundational questions	Novice	Scaffold, define terms
Points out edge cases	Expert	Engage nuance
Short responses	Overwhelmed or disengaged	Simplify

Role Signals

Signal	Likely role	Adjust
"What's the ROI?"	Decision-maker	Lead with business impact
"How do I do X?"	Practitioner	Give the recipe
"What's the evidence?"	Evaluator	Provide methodology
"Can you explain X?"	Learner	Scaffold from simple

Scope

Sensei covers knowledge transfer across three modes:

The Three Modes

Mode	What	Techniques
Conversation	Explaining in chat, answering questions	Gauge expertise, adapt, scaffold
Single Doc	One document that stands alone	Diataxis, cognitive load, structure
Collection	Multiple docs forming a knowledge system	Information architecture, single source of truth, linking flow

Where Sensei Applies

Context	Mode	Sensei applies
Chat explanation	Conversation	Yes — gauge and adapt
README, guide	Single doc	Yes — structure for audience
Documentation site	Collection	Yes — architecture matters
Code review	Conversation	Yes — explain why
Presentation	Single doc	Yes — structure for impact

Document-Level Principles

How People Read

People scan, not read. F-pattern: eyes sweep top, then down left edge.

• Front-load keywords in headings and paragraphs
• Headers as signposts
• Bullets and bold for scannability
• Wall of text = bounce

See: reading-patterns

Cognitive Load

Working memory is limited. Three types of load:

Type	Your job
Intrinsic	Can't change difficulty, but can sequence it
Extraneous	Minimize ruthlessly
Germane	This is where learning happens — protect it

See: cognitive-load

Doc Type (Diataxis)

Reader says	Write a
"Teach me X"	Tutorial
"How do I do X?"	How-to
"Why does X work?"	Explanation
"What exactly is X?"	Reference

Don't mix types. See: diataxis

AI Writing Tell-Tales

LLM text has statistical signatures. "AI slop" triggers disengagement.

Avoid: delve, leverage, utilize, robust, excessive bold, uniform paragraphs, rule-of-three abuse, generic openings.

The fix: specifics over adjectives, direct statements, natural rhythm.

See: ai-writing-antipatterns

Collection-Level Principles

Document-level principles aren't enough. Collections need architecture.

Single Source of Truth

Each fact lives in one place. Everywhere else links to it.

Instead of	Do this
Explain research in every doc	Explain once in reference, link
Repeat key tables	One location, reference it

Why: Redundancy increases cognitive load, dilutes impact, creates maintenance burden.

Progressive Disclosure at Architecture Level

Structure the collection as layers:

Entry point (30 sec) → Explanation (5 min) → Reference (verify) → Bibliography (sources)

Each layer is complete for its audience. Nobody reads more than they need.

Linking Flow

Information flows downward. Links point to deeper layers.

See: collection-architecture

Visual Communication (Diagrams)

Diagrams are teaching tools. Choose based on what you're explaining, not what's trendy.

Tool Selection

Need	Tool	Why
Quick docs, GitHub/GitLab native	Mermaid	Zero build step, renders in markdown
Complex architecture (50+ nodes)	D2	Better layouts, requires build step
Formal C4 models	C4-PlantUML	Production-proven, enterprise standard

Mermaid (Default)

Use for 95% of documentation diagrams:

• sequenceDiagram: API calls, message flow
• flowchart: Process flow, decision trees
• stateDiagram-v2: State machines, lifecycles
• erDiagram: Database schema, data models
• classDiagram: OOP structure, interfaces

Platform reality: GitHub uses ~10.0.2. Newer types (timeline, mindmap, architecture-beta) may not render.

See: mermaid-types, diagram-gotchas

D2 (When Mermaid Isn't Enough)

Upgrade to D2 when:

• Auto-layout produces spaghetti
• Need precise positioning
• Complex architecture diagrams

Trade-off: Requires build step, no native GitHub rendering.

See: d2

C4 Model

For architecture documentation:

• Context (Level 1): System boundary, users, external systems
• Container (Level 2): High-level tech choices, communication

Most teams only need Context + Container diagrams.

See: c4-architecture

Agent: feynman

For autonomous teaching work:

Task(subagent_type="sensei-1337:feynman", prompt="...")

The agent applies the full progression: Psychology → Audience → Craft → Translation

Works for:

• Writing documentation
• Explaining concepts in conversation
• Evaluating existing docs
• Technical writing for impact

Sources

Core references in references/:

Teaching & Communication:

• accuracy-integrity — why accuracy comes before technique
• reader-psychology — how readers process information
• audience-empathy — understanding who you're teaching
• rhetoric-for-impact — BLUF, inverted pyramid, translation
• cognitive-load — working memory and learning
• diataxis — document types
• feynman-technique — simplification method
• reading-patterns — how people scan
• ai-writing-antipatterns — what to avoid

Documentation Architecture:

• collection-architecture — organizing multiple documents
• information-architecture — where content lives, findability

Visual Communication (Diagrams):

• mermaid-types — Mermaid diagram catalog with syntax
• diagram-gotchas — platform issues and debugging
• d2 — D2 for complex architecture diagrams
• c4-architecture — C4 model for system documentation