Enrich Teaching Guide

Process

Step 1: Resolve Scope

Parse the user's input to determine which lessons to process.

# For "ch 3" — discover chapter path:
ls -d apps/learn-app/docs/*/03-*/

# List lesson files (exclude README, summary, quiz):
ls apps/learn-app/docs/<part>/<chapter>/*.md | grep -v README | grep -v summary | grep -v quiz

Build an ordered list of lessons to process. Process sequentially — each lesson needs the previous one as context.

Step 2: For Each Lesson — Gather Context

For lesson N, read these files in this order:

1. Lesson N-1 (previous lesson) — read FULL content

   • Purpose: understand what students already know, what vocabulary is established, what concepts are fresh
   • If N=1, skip — note "this is the chapter opener"

2. Lesson N (target) — read FULL content + all existing frontmatter

   • Purpose: deep understanding of what this lesson teaches
   • Note which frontmatter fields already exist vs missing

3. Lesson N+1 (next lesson) — read ONLY the title and first 2 headings

   • Purpose: know where the lesson arc is heading (for "this leads into..." tips)
   • If last lesson, skip — note "this is the chapter closer"

DO NOT read the chapter README. The value is in actual lesson content, not chapter metadata.

Step 3: Analyze the Lesson

Before generating, answer these questions internally:

For key_points:

"If a teacher has 2 minutes to prep, what 3 things must they know about THIS lesson?"

Look for:

• Concepts that are foundational (used again later in the chapter or book)
• Pivotal distinctions the lesson makes (X vs Y comparisons)
• Non-obvious connections to prior lessons ("this builds on the OODA loop from lesson 1")

For misconceptions:

"Where will students confidently get it WRONG?"

Look for:

• Terms that sound familiar but mean something specific here
• Concepts that seem similar but are fundamentally different
• Assumptions students bring from other tools/contexts
• The lesson's own "this is NOT..." warnings

For discussion_prompts:

"What question would make a student STOP and think for 30 seconds?"

Look for:

• Questions that connect lesson content to the student's own experience
• "What if..." counterfactuals that test understanding
• Questions with no single right answer (genuine discussion, not recall)

For teaching_tips:

"What would a veteran teacher of this lesson whisper to a first-time instructor?"

Look for:

• The best entry point (which example/scenario to start with)
• Live demo opportunities
• Whiteboard-worthy diagrams or tables in the lesson
• Pacing advice ("spend more time on X, students breeze through Y")

For assessment_quick_check:

"In 60 seconds at the end of the lesson, how can a teacher know if students got it?"

Look for:

• "Explain X in one sentence" checks for core concepts
• "Draw/diagram Y from memory" for frameworks/processes
• "What's the difference between A and B?" for key distinctions

Step 4: Generate the YAML Block

Generate a teaching_guide block matching this exact schema:

teaching_guide:
  lesson_type: "core" # core | supplementary | hands-on | capstone
  session_group: 1 # Which session/class this belongs to (integer)
  session_title: "Session Name" # Human-readable session grouping
  key_points:
    - "Point with specific detail, not generic advice"
    - "Reference to where concept recurs: 'used again in Ch X, lesson Y'"
    - "Maximum 4 points — if you need more, the lesson is too dense"
  misconceptions:
    - "Specific misconception — what students think vs what's true"
    - "Maximum 4 — focus on the dangerous ones"
  discussion_prompts:
    - "Open-ended question connecting to student experience?"
    - "Counterfactual or 'what if' that tests understanding?"
    - "Maximum 3 — quality over quantity"
  teaching_tips:
    - "Specific, actionable advice with lesson reference"
    - "Maximum 4 tips"
  assessment_quick_check:
    - "Quick check that takes <30 seconds per student"
    - "Maximum 3 checks"

Constraints:

• lesson_type: Infer from content — core (teaches new concepts), supplementary (extends/enriches), hands-on (primarily exercises), capstone (integrates multiple concepts)
• session_group: Infer from lesson position. Lessons 1-3 → session 1, 4-6 → session 2, etc. Adjust based on natural breakpoints.
• Every string must be a single line (no multiline YAML strings)
• No generic advice. Every point must reference specific lesson content.
• Use quotes consistently for all string values.

Step 5: Inject or Present

If processing 1-3 lessons: Present the generated YAML for review before injecting.

If processing 4+ lessons (batch mode): Inject directly into each lesson's frontmatter, placing the teaching_guide block after the differentiation block (or at the end of frontmatter if differentiation doesn't exist).

Injection rules:

• If teaching_guide already exists: SKIP unless user passed --force
• Preserve all existing frontmatter — only ADD the teaching_guide block
• Maintain YAML indentation (2 spaces)

Step 6: Report

After processing, output a summary:

ENRICHMENT COMPLETE
──────────────────
Lessons processed: X
Lessons skipped (already enriched): Y
Lessons enriched: Z

Files modified:
  ✓ apps/learn-app/docs/.../01-lesson.md
  ✓ apps/learn-app/docs/.../02-lesson.md
  ⊘ apps/learn-app/docs/.../03-lesson.md (already has teaching_guide)

Anti-Patterns

Handling Edge Cases

• Lesson has no learning_objectives: Generate teaching_guide anyway — the lesson content is sufficient input
• First lesson in chapter: Note "chapter opener" — tips should include "set expectations for the chapter arc"
• Last lesson in chapter: Note "chapter closer" — tips should include "connect back to chapter themes"
• Very short lesson (<500 words): May only need 2 key_points, 1-2 misconceptions
• Hands-on/exercise lesson: Focus teaching_tips on facilitation; assessment_quick_check on output verification

Reference: High-Quality Example

From Chapter 3, Lesson 1 (01-origin-story.md):

teaching_guide:
  lesson_type: "core"
  session_group: 1
  session_title: "Getting Started with Claude Code"
  key_points:
    - "OODA loop is foundational — referenced again in Chapters 5, 11, and 13"
    - "Product Overhang explains why capability existed before the product — this mental model recurs throughout the book"
    - "General Agent vs Custom Agent distinction is the entire thesis of the book"
  misconceptions:
    - "Students confuse General Agents with ChatGPT-style chatbots — emphasize the action-taking (agentic) difference"
    - "Students think 'agentic' means 'smarter' rather than 'can take actions on files and systems'"
    - "Students assume Claude Code requires coding skills — Cowork section addresses this"
  discussion_prompts:
    - "What would change in your daily work if AI could see your actual files instead of you describing them?"
    - "Can you think of other 'product overhangs' in technology — capabilities that existed but needed a better interface?"
    - "Why do you think adoption hit 50% in 5 days internally at Anthropic?"
  teaching_tips:
    - "Start with the ChatGPT copy-paste pain point — every student has experienced this"
    - "Demo the OODA loop live: show Claude reading a file, deciding what to do, acting, then correcting"
    - "The General Agent vs Custom Agent table is a good whiteboard moment"
  assessment_quick_check:
    - "Ask students to explain passive vs agentic AI in one sentence"
    - "Have students draw the OODA loop from memory"

Notice: every point is specific to this lesson. No generic teaching advice. A teacher reading this for the first time can immediately use it.