score-explanation

name	score-explanation
description	Evaluate teach-back explanations and identify knowledge gaps

Teach-Back Explanation Scorer

Evaluate a learner's open-ended explanation of a topic by comparing it against the source research material and identifying knowledge gaps.

Input

• {{TOPIC_ID}} -- identifier for the topic (used to locate research files)
• {{TOPIC_TITLE}} -- human-readable title of the topic
• {{LEARNER_EXPLANATION}} -- the learner's free-form explanation in their own words
• {{RESEARCH_DIR}} -- path to the directory containing research markdown files

Procedure

1. Locate research material. Use Glob to find research files in {{RESEARCH_DIR}} that match the topic. Look for files containing {{TOPIC_ID}} in the filename or path.

2. Read the source material. Read the matching research files to build a complete picture of what the learner should know about {{TOPIC_TITLE}}.

3. Extract key concepts. From the research, identify the distinct concepts, facts, principles, and relationships that constitute a thorough understanding of the topic.

4. Compare the learner's explanation against the key concepts on each dimension:

Evaluation Dimensions

1. Completeness (0-100) -- What percentage of key concepts did the learner cover? Count covered concepts against total key concepts.

2. Accuracy (0-100) -- Were the learner's statements technically correct? Deduct for factual errors, overgeneralizations, or misleading claims.

3. Depth -- Classify overall depth:

   • "surface" -- Recites definitions or bullet points without elaboration
   • "moderate" -- Explains how and why, not just what
   • "deep" -- Demonstrates genuine understanding through examples, analogies, trade-off analysis, or connections to other topics

4. Connections -- Did the learner link this topic to related concepts, real-world applications, or other topics in the study material?

Feedback Construction

• Covered well: List concepts the learner explained accurately and thoroughly. Be specific.
• Partially correct: List concepts the learner addressed but got partially wrong or missed important nuance. Briefly note what was missing.
• Missing entirely: List key concepts the learner did not mention at all.
• Follow-up question: Craft one targeted question that probes their weakest area. The question should invite them to think more deeply, not just recall a fact.
• Overall feedback: A 2-3 sentence summary of where they stand and what to focus on next.

Output Format

Return a single JSON object:

{
  "completeness": 65,
  "accuracy": 80,
  "depth": "moderate",
  "coveredWell": [
    "Correctly explained the role of X in the system",
    "Good example of how Y affects Z"
  ],
  "partiallyCorrect": [
    "Mentioned caching but did not distinguish between client-side and server-side caching"
  ],
  "missing": [
    "No mention of consistency trade-offs",
    "Did not address failure modes"
  ],
  "followUpQuestion": "You explained how caching improves performance, but what happens when the cached data becomes stale? How would you handle that?",
  "overallFeedback": "You have a solid grasp of the core mechanics but are missing some important trade-offs and failure scenarios. Focus your review on what happens when things go wrong, not just the happy path."
}

Notes

• Do not penalize for informal language or unconventional structure. Judge understanding, not polish.
• If the research material is not found, report that clearly rather than fabricating an evaluation.
• A learner who uses their own examples or analogies (even imperfect ones) is demonstrating deeper understanding than one who parrots the source material.