lesson-design

Files (9)

• SKILL.md
• lesson-contract.md · references/
• lesson-design.md · references/
• representation-choices.md · references/
• simulation-design.md · references/
• worker-brief.md · references/
• build_block_context.py · scripts/
• visual_levels.py · scripts/
• simulation.html · templates/

SKILL.md (first lines)

# 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.

## Repair from reviewed exercises

Before authoring a follow-up lesson for “finished” or “next”, follow
[exercise review](../learner-tracking/references/exercise-review.md). Read the
current lesson, original prompts and criteria, actual attempts, and assistance;
do not rely only on a progress label. Inspect whether the explanation prepared
the exercise. Deepen or replace the block where reasoning breaks, add a distinct
worked contrast when useful, and keep the lesson's terms and flow connected.
Publish a revised draft through the normal review/ready workflow. Record source
attempts, changed blocks, diagnosis, and a fresh verification task in the lesson
review receipt. A correct retry of a disclosed answer does not verify the repair.
Return to course-design for a new prerequisite, concept, source, or topic boundary.

## 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. [Developing the explanation](references/lesson-design.md).
   Read it before drafting and again when reviewing the assembled lesson.
4. [The lesson contract](references/lesson-contract.md).
   It defines `lesson.json`.
5. [Representation choices](references/representation-choices.md).
   Use it to choose a medium for each teaching job.
6. [The artifact manifest](../course-design/references/artifact-manifest.md).
   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](../khan-academy/SKILL.md)
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](../khan-academy/references/selection.md) 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.

| Representation kind | Lesson block type |
| --- | --- |
| `manim` | `voice-animation` |
| `image` | `diagram` or `artifact` |
| `diagram` | `diagram` or `artifact` |
| `simulation` | `interactive-graph` or `simulation` |
| `pdf` | `artifact` |
| `text` | `explanation`, `bullets`, `equation`, `code`, `source` |
| `exercise` | `exercise` |
| `khan` | `khan-video` |
| Khan Academy article or exercise | `source` |

For a mathematical graph, follow the selection rules in representation choices
and use [JSXGraph](../jsxgraph/SKILL.md) 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:

From madhvantyagi/Gnos, MIT.

More from madhvantyagi/Gnos