/teach @doc1.md @doc2.md    # Explicit files (preferred)
/teach                       # Prompts for topic/files

1. User invokes /teach @doc.md

2. List ALL existing topic directories:
   ls ~/.skulto/teach/

   Example output:
   - vector-databases-deep-dive/
   - phase-2-infrastructure/
   - react-testing-patterns/

3. Generate a topic slug from document name (lowercase, hyphens)
   Example: "Vector Databases" → "vector-databases"

4. FUZZY MATCH against existing directories (90%+ similarity):

   Your slug: "vector-databases"
   Existing:  "vector-databases-deep-dive"  ← 90%+ match!

   Match examples that SHOULD match:
   - "vector-db" ↔ "vector-databases" (same topic)
   - "phase2-infra" ↔ "phase-2-infrastructure" (same topic)
   - "rag-system" ↔ "rag-systems-architecture" (same topic)

   DO NOT create a new directory if a close match exists.

5. If MATCH FOUND (90%+ similar):

   Read the existing progress.md, show summary:

     "Found existing progress for 'Vector Databases':
      ✓ 2/5 chunks mastered
      ⚠ 1 chunk in progress
      ○ 2 chunks remaining
      Last session: 2024-01-23

      Resume where you left off, or start fresh?"

   Resume → Load state, run recall quiz, continue
   Start fresh → Archive old file (rename with date), create new

6. If NO MATCH (nothing 90%+ similar):
   Create new directory and progress.md, proceed normally

mkdir -p ~/.skulto/teach/{topic-slug}

digraph teach_flow {
    rankdir=TB;
    node [shape=box];

    intake [label="1. INTAKE\nReview docs deeply\nIdentify complexity level"];
    chunk [label="2. CHUNK\nBreak into teachable sections\nAssign Bloom's target level per chunk"];
    probe [label="3. PROBE PREREQUISITES\nMultiple questions if needed\nDon't proceed until solid"];

    assess [label="Prerequisites Solid?" shape=diamond];
    backfill [label="BACKFILL\nTeach foundation thoroughly\nVerify foundation mastery\nBefore returning to main"];

    teach_chunk [label="4. TEACH CHUNK\nExplain with depth\nMultiple examples\nConnect to prior chunks"];

    mastery [label="5. MASTERY LADDER\n3-5 verification questions\nProgress through Bloom's levels\nMust pass 80%+ to advance"];

    mastery_check [label="80%+ Correct?" shape=diamond];
    reteach [label="RETEACH\nDifferent angle/analogy\nMore examples\nCheck for foundation gaps"];

    foundation_check [label="Foundation Problem?" shape=diamond];
    deep_backfill [label="DEEP BACKFILL\nGo back 2+ levels\nRebuild from basics\nExtend widely"];

    consolidate [label="6. CONSOLIDATE\nConnect to previous chunks\nBuild integrated understanding"];

    break_check [label="Natural break?" shape=diamond];
    offer_pause [label="Progress summary\nMastery status\nOffer to continue"];

    more_chunks [label="More chunks?" shape=diamond];
    synthesis [label="7. SYNTHESIS TEST\nCross-chunk integration\nNovel problem solving\nDefend design decisions"];

    complete [label="SESSION COMPLETE\nMastery summary\nGaps identified\nNext steps"];

    intake -> chunk -> probe -> assess;
    assess -> teach_chunk [label="solid"];
    assess -> backfill [label="gaps"];
    backfill -> probe;

    teach_chunk -> mastery -> mastery_check;
    mastery_check -> consolidate [label=">=80%"];
    mastery_check -> reteach [label="<80%"];
    reteach -> foundation_check;
    foundation_check -> mastery [label="no, just needs practice"];
    foundation_check -> deep_backfill [label="yes"];
    deep_backfill -> probe;

    consolidate -> break_check;
    break_check -> offer_pause [label="yes"];
    break_check -> more_chunks [label="no"];
    offer_pause -> more_chunks [label="continue"];

    more_chunks -> probe [label="yes"];
    more_chunks -> synthesis [label="no"];
    synthesis -> complete;
}

CHUNK: Understanding Vector Embeddings

Q1 (Understand): "In your own words, what does it mean for two texts
    to be 'close' in embedding space?"

Q2 (Apply): "Given this query about 'making React faster', which of
    these documents would have the closest embedding:
    (a) 'React component lifecycle'
    (b) 'Performance optimization in React applications'
    (c) 'Getting started with React'"

Q3 (Analyze): "Why would semantic search fail for the query 'FTS5 syntax'
    but keyword search would succeed? What's different about these query types?"

Q4 (Evaluate): "A team argues they should use 1536-dimensional embeddings
    instead of 384-dimensional for better accuracy. What's your response?
    What factors should they consider?"

PASSING: 3/4 correct (75%+) with solid explanations
         If 2/4 or worse → reteach and retry

Teacher: "Before we discuss vector databases, I need to check
your foundation. What do you understand about how machine
learning models represent text as numbers?"

[If vague or wrong]
Teacher: "That's a gap we need to fill first. Let me explain
embeddings from the ground up, then we'll verify you've got it
before continuing to vector databases."

[Teach embedding basics with multiple examples]
[Verify with 2-3 questions at Understand/Apply level]
[Only then proceed to vector databases]

Teacher: "Good. Let's consolidate. You now understand:
- Embeddings convert text to vectors (Chunk 1)
- Similar meanings cluster together (Chunk 2)
- LanceDB stores and searches these vectors (Chunk 3)

Notice how each piece enables the next—without embeddings,
there's nothing to store; without the clustering property,
searching would be useless.

Next chunk will cover the indexing pipeline. You'll need to
hold all three concepts together. Ready?"

Good stopping point.

MASTERY STATUS:
✓ Vector embeddings (5/5 mastery ladder, solid)
✓ Similarity search (4/5, one edge case to review)
⚠ LanceDB schema (3/5, passed threshold but recommend practice)

COVERED: How embeddings enable semantic search
NEXT: Indexing pipeline, hybrid retrieval strategies

Continue, or save progress for later?