build-explanations

What this skill does

# 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](references/accuracy-integrity.md)

## 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](references/reader-psychology.md)

### 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](references/audience-empathy.md)

### 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](references/diataxis.md), [rhetoric-for-impact](references/rhetoric-for-impact.md), [cognitive-load](references/cognitive-load.md), [feynman-technique](references/feynman-technique.md), [collection-architecture](references/collection-architecture.md), [information-architecture](references/information-architecture.md)

### 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](references/rhetoric-for-impact.md)

## 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](references/reading-patterns.md)

### 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](references/cognitive-load.md)

### 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 |

Do