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

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:

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:

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%.

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

Role Signals

Scope

Sensei covers knowledge transfer across three modes:

The Three Modes

Where Sensei Applies

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:

See: [cognitive-load](references/cognitive-load.md)

Doc Type (Diataxis)

Don't mix types. See: [diataxis](references/diataxis.md)

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](references/ai-writing-antipatterns.md)

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.

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](references/collection-architecture.md)

Visual Communication (Diagrams)

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

Tool Selection

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](references/mermaid-types.md), [diagram-gotchas](references/diagram-gotchas.md)

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](references/d2.md)

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](references/c4-architecture.md)

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](references/accuracy-integrity.md) — why accuracy comes before technique
• [reader-psychology](references/reader-psychology.md) — how readers process information
• [audience-empathy](references/audience-empathy.md) — understanding who you're teaching
• [rhetoric-for-impact](references/rhetoric-for-impact.md) — BLUF, inverted pyramid, translation
• [cognitive-load](references/cognitive-load.md) — working memory and learning
• [diataxis](references/diataxis.md) — document types
• [feynman-technique](references/feynman-technique.md) — simplification method
• [reading-patterns](references/reading-patterns.md) — how people scan
• [ai-writing-antipatterns](references/ai-writing-antipatterns.md) — what to avoid

Documentation Architecture:

• [collection-architecture](references/collection-architecture.md) — organizing multiple documents
• [information-architecture](references/information-architecture.md) — where content lives, findability

Visual Communication (Diagrams):

• [mermaid-types](references/mermaid-types.md) — Mermaid diagram catalog with syntax
• [diagram-gotchas](references/diagram-gotchas.md) — platform issues and debugging
• [d2](references/d2.md) — D2 for complex architecture diagrams
• [c4-architecture](references/c4-architecture.md) — C4 model for system documentation