# Yzavyas Claude 1337 Build Explanations > sensei-1337 - Skill: `tomevault-io/yzavyas-claude-1337-build-explanations` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/yzavyas-claude-1337-build-explanations` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/yzavyas-claude-1337-build-explanations/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/yzavyas-claude-1337-build-explanations --- # 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 | 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. | 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](references/collection-architecture.md) ## 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](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 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/yzavyas) — claim your Tome and manage your conversions.