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

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:

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:

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

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

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

Cognitive Load

Working memory is limited. Three types of load:

See: cognitive-load

Doc Type (Diataxis)

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.

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

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