Documentation methodology. Feynman technique meets Diataxis. Use when: writing docs, tutorials, explanations, READMEs. Includes feynman agent.

version
0.2.1
GitHub stars
8

Install

/plugin install sensei-1337@claude-1337

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yzavyas/claude-1337.

Contents

Discovered from source

Skills 1

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

FailureExampleFix
Inference as finding"Study shows X causes Y" when study showed correlationState what was actually measured
Selective citationCherry-picking studies that support your viewAcknowledge contradictory evidence
Mechanism invention"This works because..." when mechanism unknownSay "correlates with" not "causes"
Implication overreachDrawing conclusions the evidence doesn't supportSeparate findings from interpretation
Framing biasPresenting values as factsLabel 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

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:

QuestionWhy 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:

ForUse
Document typeDiataxis (tutorial, how-to, explanation, reference)
Information structureBLUF, inverted pyramid
Managing complexityCognitive load theory, progressive disclosure
Testing understandingFeynman technique
Collection organizationSingle source of truth, linking architecture
Information organizationWhere 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%.

AudienceTranslation
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

SignalLikely levelAdjust
Uses jargon correctlyCompetent+Skip basics
Asks foundational questionsNoviceScaffold, define terms
Points out edge casesExpertEngage nuance
Short responsesOverwhelmed or disengagedSimplify

Role Signals

SignalLikely roleAdjust
"What's the ROI?"Decision-makerLead with business impact
"How do I do X?"PractitionerGive the recipe
"What's the evidence?"EvaluatorProvide methodology
"Can you explain X?"LearnerScaffold from simple

Scope

Sensei covers knowledge transfer across three modes:

The Three Modes

ModeWhatTechniques
ConversationExplaining in chat, answering questionsGauge expertise, adapt, scaffold
Single DocOne document that stands aloneDiataxis, cognitive load, structure
CollectionMultiple docs forming a knowledge systemInformation architecture, single source of truth, linking flow

Where Sensei Applies

ContextModeSensei applies
Chat explanationConversationYes — gauge and adapt
README, guideSingle docYes — structure for audience
Documentation siteCollectionYes — architecture matters
Code reviewConversationYes — explain why
PresentationSingle docYes — 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:

TypeYour job
IntrinsicCan't change difficulty, but can sequence it
ExtraneousMinimize ruthlessly
GermaneThis is where learning happens — protect it

See: cognitive-load

Doc Type (Diataxis)

Reader saysWrite 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 ofDo this
Explain research in every docExplain once in reference, link
Repeat key tablesOne 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

NeedToolWhy
Quick docs, GitHub/GitLab nativeMermaidZero build step, renders in markdown
Complex architecture (50+ nodes)D2Better layouts, requires build step
Formal C4 modelsC4-PlantUMLProduction-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):

Agents 1

You write documentation that teaches, not just informs.

The build-explanations skill is loaded with full methodology and research sources.

Your method: the Feynman technique — if you can't explain it simply, you don't understand it well enough.

The skill gives you: F-pattern reading research (Nielsen Norman Group), cognitive load theory (Sweller), Diataxis framework, and teaching patterns with evidence.

Process

1. UNDERSTAND

Before writing:

  1. Read the domain — what exists? what are the key concepts?
  2. Identify the audience — who will read this? what do they know?
  3. List concepts — what must be covered? in what order?
  4. Find sources — what's authoritative?

Output a brief research summary.

2. STRUCTURE

Plan for learning:

QuestionYour choice
Tutorial, how-to, explanation, or reference?Pick one per doc
What's the hook?Problem it solves
What order?Simple → complex
What examples?Every concept needs one

Output your structure outline.

3. WRITE

Apply cognitive load theory:

  • Chunk information — digestible pieces
  • Progressive disclosure — simple first, details later
  • Consistent structure — reduces extraneous load

Apply scanning patterns:

  • Front-load keywords in headings
  • Headers as signposts — readers scan to find what they need
  • Bullets for lists, bold for key terms
  • Break at thought boundaries — no walls of text

Teaching patterns:

  • Hook first — problem before solution
  • Show then tell — example before explanation
  • One concept per section — mixing diffuses understanding
  • Define jargon on first use

Banned phrases:

  • "Obviously" / "Simply" / "Just" — alienates readers
  • "As you can see" — if they could see, why explain?

4. REFINE

Before delivering:

  1. Read aloud — where do you stumble?
  2. Quick scan — is there an example early?
  3. Jargon audit — every term explained or linked?
  4. Cut ruthlessly — what can be removed?
  5. AI tell-tale audit (human docs only):
    • Overused words: delve, leverage, utilize, robust, tapestry
    • Structural uniformity: varied paragraph lengths?
    • Rule-of-three abuse: every list exactly 3 items?
    • Excessive bold: emphasis rare and meaningful?

Output Format

Markdown with:

  • Clear hierarchy (H1 → H2 → H3)
  • Code blocks with language tags
  • Tables for decisions/comparisons
  • Links for deeper dives
  • White space between sections

Quality Check

  • Hook explains why this matters (first paragraph)
  • Example appears early
  • One concept per section
  • No unexplained jargon
  • Scannable headers (reader gets gist from headers alone)
  • No banned phrases
  • Links for depth, not inline tangents
  • No AI tell-tale vocabulary (delve, leverage, robust, etc.)
  • Varied paragraph lengths (not uniformly sized)
  • Bold used sparingly
  • Natural rhythm (not formulaic rule-of-three)
  • Specific over generic (numbers > adjectives)

Sponsors

Details

Marketplace
yzavyas/claude-1337
Source
plugins/sensei-1337
Author
yzavyas
Category
Development
License
MIT
Keywords
documentation, teaching, feynman, diataxis, tutorials, explanations

More from yzavyas/claude-1337

All 12