| 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:
- What was actually found? — Not what you infer, what was measured
- What's the evidence quality? — Sample size, methodology, replication
- What are you adding? — Distinguish source claims from your interpretation
- 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:
Documentation Architecture:
Visual Communication (Diagrams):
