Lesson Design

Lesson design

Build only the lesson for the current topic. The course is already enrolled and designed by course-design. Do not rebuild the course here.

Start here after course-design has enrolled the course. If there is no enrolled learners/<learner>/courses/<course-id>/course.json, stop and return to course-design. Return there for a new concept, source, or topic boundary. Choose media and develop explanations here; those choices alone do not require a course revision unless the topic has a binding representation plan.

0. Read the current topic

Read these before writing anything:

1. The enrolled course.json: depth, length, current.{chapter_id, topic_id}, and that topic's optional representations[], skill_routes, concepts, and teacher.
2. The subject guide through skills/subject/SKILL.md. It says what learners in this field must inspect.
3. The lesson contract. It defines lesson.json.
4. Representation choices. Use it to choose a medium for each teaching job.
5. The artifact manifest. Only the coordinator writes it.

For a core concept or an unverified prerequisite that Khan Academy can explain at the needed level, use the Khan Academy skill to inspect an exact item before choosing it. A prerequisite clip should repair one gap and lead straight back to this topic. A main-topic clip should sit between a specific prediction and GNOS's own explanation or changed example. Use Khan for an important section when it fits, and reuse it only when a later section needs that exact content. Read its selection reference to distinguish target-topic coverage from prerequisite-only coverage. Keep diagrams, code, derivations, simulations, and other forms where they serve the remaining reasoning. Do not add a generic resource list or assume watching proves understanding.

depth and length were agreed during course design. Use them to decide how far to develop the reasoning and each representation. A survey needs a carefully chosen central case; working depth needs application under changed conditions; mastery needs closer examination of assumptions and limits. Choose complementary forms for those jobs, including within one concept. Duration alone neither requires more media nor limits a useful combination.

Decide each representation

Choose the block type while drafting the reasoning. Write one sentence per block before you build it:

"The learner must inspect, change, hear, compare, derive, or practice ___."

Give each representation a distinct teaching job. Several forms can develop one concept: a video can demonstrate a relation, a diagram can keep its parts inspectable, and a simulation can test a changed input. Remove repetition that adds no new explanation, observation, or practice.

For a mathematical graph, follow the selection rules in representation choices and use JSXGraph when they fit. Declare its production route in the lesson as with the other media skills. It uses the existing interactive-graph or simulation blocks; the graph library does not add a new representation kind.

When the topic has a representation plan, bind a block to the matching entry with representation_id and keep its concept, purpose, kind, and skill route. For a topic without that plan, choose the medium during lesson design. In either case, put a Khan video in its own khan-video block with a prompt tied to this lesson's concept and the next learner action. Check the actual segment before publishing and follow it with GNOS's own example or exercise. If a planned representation is wrong, revise and validate course.json before changing the lesson.

1. Write the skeleton in reasoning order

A lesson.json holds id, course_id, chapter_id, topic_id, readable title, observable purpose, concepts from the topic, the topic's teacher (or null), skill_routes carrying the topic guidance and chosen media producers, assumptions, ordered blocks, detailed exercises, publication (draft, ready, or archived), and real UTC timestamps.

Order blocks by reasoning, not by file type. A good order names the claim, lets the learner inspect its changing parts, then asks for a prediction. When a topic has a representation plan, use its approved media or revise that plan. Without a plan, choose the media that teach the current concept.

Validate the skeleton and publish it as draft before producing files. The draft gives every artifact a real lesson ID:

python3 skills/course-design/scripts/validate_lesson.py lesson.json \
  --course learners/<learner>/courses/<course-id>/course.json
python3 skills/course-design/scripts/course_workspace.py publish \
  learners/<learner>/courses/<course-id> --lesson lesson.json