Initial commit

2025-11-29 18:48:58 +08:00
commit df092d8cd2
127 changed files with 62057 additions and 0 deletions
--- a/skills/reading-teacher/references/comprehension.md
+++ b/skills/reading-teacher/references/comprehension.md
@@ -0,0 +1,636 @@
+# Reading Comprehension Reference
+
+Strategies, question types, and interactive activities for developing reading comprehension.
+
+## Comprehension Strategies
+
+### Before Reading
+```javascript
+const beforeReadingStrategies = {
+  preview: {
+    name: 'Preview the Text',
+    steps: [
+      'Look at title and pictures',
+      'Read headings and subheadings',
+      'Predict what story is about',
+      'Ask: What do I already know about this topic?'
+    ],
+    prompt: 'What do you think this story will be about?'
+  },
+
+  purpose: {
+    name: 'Set a Purpose',
+    steps: [
+      'Why am I reading this?',
+      'What do I want to learn?',
+      'How will I use this information?'
+    ],
+    prompt: 'What do you want to find out from this story?'
+  },
+
+  vocabulary: {
+    name: 'Preview Key Words',
+    steps: [
+      'Identify unfamiliar words',
+      'Look at context',
+      'Check pictures for clues',
+      'Make predictions about meanings'
+    ],
+    prompt: 'Are there any new words? What might they mean?'
+  }
+};
+```
+
+### During Reading
+```javascript
+const duringReadingStrategies = {
+  visualize: {
+    name: 'Make Mental Pictures',
+    prompt: 'What do you see in your mind?',
+    activity: 'Draw what you\'re imagining'
+  },
+
+  question: {
+    name: 'Ask Questions',
+    prompts: [
+      'What is happening?',
+      'Why did that happen?',
+      'What will happen next?',
+      'How does the character feel?'
+    ]
+  },
+
+  connect: {
+    name: 'Make Connections',
+    types: {
+      textToSelf: 'Has this happened to you?',
+      textToText: 'Does this remind you of another story?',
+      textToWorld: 'Where have you seen this in real life?'
+    }
+  },
+
+  clarify: {
+    name: 'Fix Confusions',
+    strategies: [
+      'Reread the sentence',
+      'Read ahead for clues',
+      'Look at pictures',
+      'Sound out unfamiliar words',
+      'Ask for help'
+    ]
+  },
+
+  predict: {
+    name: 'Make Predictions',
+    prompt: 'What do you think will happen next?',
+    check: 'Was your prediction correct?'
+  }
+};
+```
+
+### After Reading
+```javascript
+const afterReadingStrategies = {
+  summarize: {
+    name: 'Retell the Story',
+    framework: {
+      beginning: 'How did the story start?',
+      middle: 'What happened?',
+      end: 'How did it end?'
+    }
+  },
+
+  mainIdea: {
+    name: 'Find the Main Idea',
+    questions: [
+      'What is the story mostly about?',
+      'What is the most important part?',
+      'What did you learn?'
+    ]
+  },
+
+  evaluate: {
+    name: 'Think About the Story',
+    questions: [
+      'Did you like it? Why?',
+      'What was your favorite part?',
+      'Would you recommend this to a friend?',
+      'What would you change?'
+    ]
+  }
+};
+```
+
+## Question Types
+
+### Literal Questions (Right There)
+```javascript
+const literalQuestions = {
+  who: 'Who is the main character?',
+  what: 'What happened in the story?',
+  when: 'When did this take place?',
+  where: 'Where does the story happen?',
+  how: 'How did the character solve the problem?',
+
+  examples: [
+    'What color was the cat?',
+    'Where did Tom go?',
+    'Who helped Sally?',
+    'When did they leave?'
+  ]
+};
+```
+
+### Inferential Questions (Think & Search)
+```javascript
+const inferentialQuestions = {
+  why: 'Why did the character do that?',
+  cause: 'What caused this to happen?',
+  effect: 'What happened because of...?',
+  feeling: 'How do you think the character felt?',
+  motive: 'Why did the character want...?',
+
+  examples: [
+    'Why was the girl sad?',
+    'How did the boy feel when...?',
+    'What made the dog run away?',
+    'Why didn\'t they tell anyone?'
+  ]
+};
+```
+
+### Evaluative Questions (Author & Me)
+```javascript
+const evaluativeQuestions = {
+  opinion: 'What do you think about...?',
+  judgment: 'Did the character make a good choice?',
+  alternative: 'What would you have done?',
+  theme: 'What lesson does this teach?',
+
+  examples: [
+    'Was it right for her to...?',
+    'What would you do in this situation?',
+    'Do you agree with the character?',
+    'What is the author trying to tell us?'
+  ]
+};
+```
+
+### Creative Questions (On My Own)
+```javascript
+const creativeQuestions = {
+  extend: 'What might happen next?',
+  change: 'How would the story be different if...?',
+  relate: 'How is this like your life?',
+  imagine: 'What if the character had...?',
+
+  examples: [
+    'What would happen if the ending was different?',
+    'How would you feel if you were the character?',
+    'What other adventures might they have?',
+    'If you could change one thing, what would it be?'
+  ]
+};
+```
+
+## Story Elements
+
+### Character Analysis
+```javascript
+const characterAnalysis = {
+  traits: {
+    prompt: 'What is the character like?',
+    evidence: 'How do you know?',
+    categories: ['brave', 'kind', 'funny', 'smart', 'curious', 'helpful']
+  },
+
+  feelings: {
+    prompt: 'How does the character feel?',
+    changes: 'How do their feelings change?',
+    emotions: ['happy', 'sad', 'angry', 'scared', 'excited', 'surprised']
+  },
+
+  actions: {
+    prompt: 'What does the character do?',
+    motives: 'Why do they do it?'
+  },
+
+  relationships: {
+    prompt: 'Who are the other characters?',
+    connections: 'How do they interact?'
+  }
+};
+```
+
+### Setting
+```javascript
+const settingAnalysis = {
+  where: {
+    prompt: 'Where does the story take place?',
+    details: 'Describe the place'
+  },
+
+  when: {
+    prompt: 'When does the story happen?',
+    clues: ['time of day', 'season', 'past/present/future']
+  },
+
+  importance: {
+    prompt: 'Does the setting matter to the story?',
+    question: 'Would the story be different in a different place/time?'
+  }
+};
+```
+
+### Plot Structure
+```javascript
+const plotStructure = {
+  beginning: {
+    name: 'Introduction',
+    elements: ['characters', 'setting', 'situation'],
+    question: 'How does the story start?'
+  },
+
+  middle: {
+    name: 'Problem/Conflict',
+    elements: ['challenge', 'obstacle', 'quest'],
+    question: 'What problem do the characters face?'
+  },
+
+  climax: {
+    name: 'Turning Point',
+    elements: ['most exciting part', 'biggest challenge'],
+    question: 'What is the most important moment?'
+  },
+
+  end: {
+    name: 'Resolution',
+    elements: ['solution', 'outcome', 'lesson'],
+    question: 'How is the problem solved?'
+  }
+};
+```
+
+## Interactive Comprehension Activities
+
+### Story Map
+```javascript
+function createStoryMap() {
+  return {
+    title: '',
+    characters: {
+      main: [],
+      supporting: []
+    },
+    setting: {
+      where: '',
+      when: ''
+    },
+    plot: {
+      beginning: '',
+      problem: '',
+      events: [],
+      solution: '',
+      ending: ''
+    },
+
+    display: function() {
+      return `
+        📖 ${this.title}
+        👥 Characters: ${this.characters.main.join(', ')}
+        📍 Setting: ${this.setting.where} (${this.setting.when})
+
+        Story:
+        Beginning: ${this.plot.beginning}
+        Problem: ${this.plot.problem}
+        Events: ${this.plot.events.join(' → ')}
+        Solution: ${this.plot.solution}
+        Ending: ${this.plot.ending}
+      `;
+    }
+  };
+}
+```
+
+### Question Generator
+```javascript
+function generateComprehensionQuestions(story, level) {
+  const questions = [];
+
+  // Literal questions (ages 5-7)
+  if (level <= 2) {
+    questions.push({
+      type: 'literal',
+      question: `Who is the main character in "${story.title}"?`,
+      answer: story.characters.main[0],
+      difficulty: 'easy'
+    });
+
+    questions.push({
+      type: 'literal',
+      question: `Where does the story take place?`,
+      answer: story.setting.where,
+      difficulty: 'easy'
+    });
+  }
+
+  // Inferential questions (ages 7-9)
+  if (level >= 2) {
+    questions.push({
+      type: 'inferential',
+      question: `Why do you think the character...?`,
+      answer: null, // Open-ended
+      difficulty: 'medium'
+    });
+
+    questions.push({
+      type: 'inferential',
+      question: `How did the character feel when...?`,
+      answer: null,
+      difficulty: 'medium'
+    });
+  }
+
+  // Evaluative questions (ages 9+)
+  if (level >= 3) {
+    questions.push({
+      type: 'evaluative',
+      question: `What would you have done differently?`,
+      answer: null,
+      difficulty: 'hard'
+    });
+  }
+
+  return questions;
+}
+```
+
+### Cloze Reading (Fill in the Blank)
+```javascript
+function createClozeActivity(text, difficulty = 'medium') {
+  const words = text.split(' ');
+  const blanks = [];
+
+  // Remove every Nth word based on difficulty
+  const interval = difficulty === 'easy' ? 10 : difficulty === 'medium' ? 7 : 5;
+
+  const modified = words.map((word, index) => {
+    if (index % interval === 0 && word.length > 3) {
+      blanks.push({
+        position: index,
+        word: word,
+        hint: word[0] + '_'.repeat(word.length - 1)
+      });
+      return '______';
+    }
+    return word;
+  });
+
+  return {
+    original: text,
+    modified: modified.join(' '),
+    blanks: blanks,
+
+    check: function(userAnswers) {
+      let correct = 0;
+      userAnswers.forEach((answer, i) => {
+        if (answer.toLowerCase() === blanks[i].word.toLowerCase()) {
+          correct++;
+        }
+      });
+      return {
+        correct: correct,
+        total: blanks.length,
+        percentage: Math.round((correct / blanks.length) * 100)
+      };
+    },
+
+    getHint: function(blankIndex) {
+      return blanks[blankIndex].hint;
+    }
+  };
+}
+```
+
+### Sequence Activity
+```javascript
+function createSequenceActivity(events) {
+  const shuffled = shuffle([...events]);
+
+  return {
+    events: events,
+    scrambled: shuffled,
+    userOrder: [],
+
+    check: function() {
+      return {
+        correct: JSON.stringify(this.userOrder) === JSON.stringify(events),
+        correctOrder: events,
+        userOrder: this.userOrder
+      };
+    },
+
+    hint: function() {
+      return `The story starts with: "${events[0]}"`;
+    }
+  };
+}
+```
+
+### Vocabulary in Context
+```javascript
+function createVocabularyActivity(text, targetWords) {
+  return targetWords.map(word => {
+    const sentence = findSentenceWith(text, word);
+    const context = getContext(text, word);
+
+    return {
+      word: word,
+      sentence: sentence,
+      beforeContext: context.before,
+      afterContext: context.after,
+
+      questions: [
+        {
+          type: 'multiple-choice',
+          question: `What does "${word}" mean in this sentence?`,
+          options: generateDefinitionOptions(word),
+          answer: getCorrectDefinition(word)
+        },
+        {
+          type: 'context-clue',
+          question: 'Which words help you understand the meaning?',
+          answer: getContextClues(sentence, word)
+        }
+      ],
+
+      practice: {
+        blank: sentence.replace(word, '______'),
+        wordBank: [word, ...generateSimilarWords(word)],
+        correctWord: word
+      }
+    };
+  });
+}
+```
+
+## Comprehension Games
+
+### Story Detective
+```javascript
+class StoryDetective {
+  constructor(story) {
+    this.story = story;
+    this.clues = [];
+    this.questions = [];
+    this.score = 0;
+  }
+
+  addClue(question, answer, location) {
+    this.clues.push({
+      question: question,
+      answer: answer,
+      found: false,
+      location: location
+    });
+  }
+
+  checkClue(clueIndex, userAnswer) {
+    const clue = this.clues[clueIndex];
+
+    if (userAnswer.toLowerCase().includes(clue.answer.toLowerCase())) {
+      clue.found = true;
+      this.score += 10;
+      return {
+        correct: true,
+        message: '🔍 Clue found! +10 points',
+        location: clue.location
+      };
+    }
+
+    return {
+      correct: false,
+      hint: `Look ${clue.location}`,
+      message: 'Keep searching!'
+    };
+  }
+
+  getProgress() {
+    const found = this.clues.filter(c => c.found).length;
+    return {
+      found: found,
+      total: this.clues.length,
+      percentage: Math.round((found / this.clues.length) * 100),
+      score: this.score
+    };
+  }
+}
+```
+
+### Reading Race
+```javascript
+class ReadingRace {
+  constructor(passage, questionsPerCheckpoint = 3) {
+    this.passage = passage;
+    this.checkpoints = this.createCheckpoints(questionsPerCheckpoint);
+    this.currentCheckpoint = 0;
+    this.startTime = null;
+    this.endTime = null;
+  }
+
+  start() {
+    this.startTime = Date.now();
+  }
+
+  answerQuestion(answer) {
+    const checkpoint = this.checkpoints[this.currentCheckpoint];
+    const question = checkpoint.questions[checkpoint.currentQuestion];
+
+    const correct = this.checkAnswer(answer, question.answer);
+
+    if (correct) {
+      checkpoint.correct++;
+      checkpoint.currentQuestion++;
+
+      if (checkpoint.currentQuestion >= checkpoint.questions.length) {
+        this.currentCheckpoint++;
+        return {
+          checkpointComplete: true,
+          message: `🏁 Checkpoint ${this.currentCheckpoint} complete!`
+        };
+      }
+    }
+
+    return { correct: correct };
+  }
+
+  finish() {
+    this.endTime = Date.now();
+    const time = (this.endTime - this.startTime) / 1000; // seconds
+
+    return {
+      time: time,
+      checkpoints: this.checkpoints.length,
+      accuracy: this.calculateAccuracy(),
+      rating: this.getRating(time, this.calculateAccuracy())
+    };
+  }
+}
+```
+
+## Progress Tracking
+
+### Comprehension Skills Tracker
+```javascript
+class ComprehensionTracker {
+  constructor() {
+    this.skills = {
+      literal: { attempts: 0, correct: 0 },
+      inferential: { attempts: 0, correct: 0 },
+      evaluative: { attempts: 0, correct: 0 },
+      vocabulary: { attempts: 0, correct: 0 },
+      sequencing: { attempts: 0, correct: 0 },
+      mainIdea: { attempts: 0, correct: 0 },
+      causeEffect: { attempts: 0, correct: 0 }
+    };
+  }
+
+  record(skillType, correct) {
+    this.skills[skillType].attempts++;
+    if (correct) this.skills[skillType].correct++;
+  }
+
+  getSkillLevel(skillType) {
+    const skill = this.skills[skillType];
+    if (skill.attempts === 0) return 'Not Started';
+
+    const accuracy = skill.correct / skill.attempts;
+
+    if (accuracy >= 0.9) return 'Mastered';
+    if (accuracy >= 0.7) return 'Proficient';
+    if (accuracy >= 0.5) return 'Developing';
+    return 'Needs Practice';
+  }
+
+  getReport() {
+    return Object.entries(this.skills).map(([name, data]) => ({
+      skill: name,
+      level: this.getSkillLevel(name),
+      accuracy: data.attempts > 0 ? Math.round((data.correct / data.attempts) * 100) : 0,
+      attempts: data.attempts
+    }));
+  }
+}
+```
+
+## Summary
+
+Reading comprehension tools provide:
+- Before, during, and after reading strategies
+- Multiple question types (literal, inferential, evaluative, creative)
+- Story element analysis (character, setting, plot)
+- Interactive activities (story maps, cloze, sequencing)
+- Comprehension games
+- Progress tracking
+
+Use these patterns to create effective comprehension practice!