lesson-builder

Lesson Builder

Turns a curriculum plan + research dossier into shipping lesson materials. The output of this skill is the set of files the learner will actually open during a session.

When to use this skill vs. others

• Plan modules and prereqs → curriculum-planner
• Find authoritative refs → lesson-researcher
• Assemble lesson/exercise/solution files → this skill
• Get drafts critiqued before student sees them → lesson-review-board
• Run the live session → professor

Inputs required

Before building, read:

1. Curriculum plan (CURRICULUM_PLAN.md) — module objectives, prereqs, exercise idea, time estimate.
2. Research dossier (research/<module>.md) — citations, quotes, version notes, inline-vs-docs-dive markings.
3. Existing course conventions — read at least one prior module's lesson.md, exercise.*, solution.* to mirror file layout, naming, and tone. Each course has its own dialect; match it.
4. Learner-specific preferences from the course PROGRESS.md and the learner's auto-memory MEMORY.md (e.g., "build composite formulas from their parts", "use 📖 callouts for docs-dive", "Pen-and-Paper Work sections", "minimal hints"). CONVENTIONS.md describes the defaults.

If any of these inputs are missing, stop and surface it — don't guess.

File layout per module

Mirror the conventions of the target course. A common layout:

• lessons/<module-id>-<slug>.md — narrative + concept + worked example + exercise prompt
• exercises/<module-id>-<slug>.{py,c,…} — TODO-skeleton with PASS/FAIL test harness baked in
• solutions/<module-id>-<slug>.{py,c,…} — full working solution
• homework/ — pen-and-paper prompts (when used) and the photos uploaded via review-handwritten-homework
• EPIPHANIES.md — append-only log of "click" moments (the professor writes these during sessions; the builder doesn't seed them)

For C / DSA courses also produce/update a Makefile target so make ex<name> and make run-<name> work.

Lesson template (default — adapt to course conventions)

See ${CLAUDE_PLUGIN_ROOT}/skills/lesson-builder/references/course-design.md for the full template. Required sections per lesson:

1. Frontmatter / header — module number, title, est. time, prerequisites
2. Learning objectives — 3–6, each demonstrable
3. Concept — the why before the how; build composite ideas from their sub-components first so the combined formula feels intuitive
4. Visual representation — ASCII diagram, memory layout, flowchart when applicable
5. Worked example — heavily commented; learner should be able to read every line and predict its effect
6. Exercise prompt — the thing they'll attempt; specify requirements + edge cases
7. Pen-and-Paper Work (when used) — by-hand sub-exercises BEFORE any code, so the learner derives the formula/algorithm/trace before typing
8. Hints (collapsed) — graded; only revealed when stuck
9. Solution pointer — link to solutions/<file> rather than inlining (some courses do inline; mirror existing convention)
10. Troubleshooting — common failures from prior learners
11. What's next

Exercise skeleton (TODO-driven)

Every exercise file ships as a TODO skeleton with a runnable test harness, not a blank file. Pattern:

# Module XX — <title>
# Goal: <one sentence>
#
# Read lesson <path> first, then fill in the TODO blocks.
# Run this file directly: PASS/FAIL prints inline.

def <function_to_implement>(...):
    """<one-line behavior contract — what it should do, NOT how>"""
    # TODO: <pointer to the relevant concept in the lesson>
    raise NotImplementedError

if __name__ == "__main__":
    # ---- tests ----
    assert <function>(input1) == expected1, "case 1"
    assert <function>(input2) == expected2, "case 2"
    print("PASS")

For C: emit a #include "test.h" style harness, with EXPECT_EQ_INT(...) macros and a single main() that runs all checks and prints PASS / FAIL: <case>.

Important: TODO docstrings describe the behavior contract — never implementation pseudocode the learner can transcribe. Pseudocode hints belong (collapsed) in the lesson, not in the skeleton.

Inline vs. docs-dive

Honor the dossier's Treatment field per concept:

• Inline — paste the quote/snippet into the lesson directly so the learner doesn't context-switch.
• Docs-dive — render as a 📖 callout: "📖 Read on before continuing. The lesson assumes you've understood ."

Default to inline for core mechanics. Reserve docs-dive for periphery or extended reading.

Assessments

When the plan calls for an assessment (mid-course checkpoint, capstone, end-of-module review), build it using the three-part structure in ${CLAUDE_PLUGIN_ROOT}/skills/lesson-builder/references/assessment-patterns.md:

1. Code review (find the bugs)
2. Pen & paper (trace, diagram, calculate, explain)
3. Implementation challenges (build from scratch)

Bugs in part 1 should mirror real mistakes the learner has actually made (from PROGRESS.md knowledge-gap notes), not generic textbook bugs.

Solution files

Solutions are full working code with comments that explain why — not just what. The professor will reveal these only after the learner has attempted the exercise. Solutions should:

• Compile/run on their own
• Pass the same test harness embedded in the exercise
• Annotate the one or two non-obvious decisions (skip annotations on trivial lines)
• Match the project's lint/format settings (run pyright/compiler/formatter before declaring done)

Build workflow

1. Read plan + dossier + one prior lesson for style.
2. Sketch lesson structure as a bullet outline. Confirm objectives match plan.
3. Draft lesson.md first (narrative + concept + worked example + exercise prompt + Pen-and-Paper Work).
4. Build exercise skeleton with passing-when-implemented test harness. Run it once empty to confirm it FAILs cleanly with a clear message.
5. Write solution file. Run test harness against it. Must PASS.
6. Wire up Makefile / build config if applicable.
7. Cross-check: every concept in the dossier appears in the lesson. Every learning objective from the plan has at least one exercise check.
8. Surface result: list files written and the next recommended step.

Anti-patterns to avoid

• Skeletons that don't run — the empty exercise must execute and emit a clear "not implemented" failure, not a syntax error.
• Solutions that disagree with the lesson — if the solution uses a pattern the lesson didn't introduce, either teach the pattern or pick a different solution.
• Padding to look comprehensive — three sharp examples beat ten shallow ones.
• Generic bugs in code-review assessments — tie bugs to this learner's gap log when possible.
• Re-teaching prereqs — if Module 03 already covered it, link back rather than re-explaining.
• Inventing curriculum on the fly — if the plan is silent or contradicts itself, stop and ask, don't paper over it.
• Hints that give away the answer — the first hint should re-frame, the second should point at a concept, the third (rarely) should pseudocode.
• Pseudocode in TODO docstrings — describe behavior, not implementation. The learner shouldn't be able to transcribe the answer from a TODO comment.

After files are written

Recommend the next step: "Module XX files written. Next: run lesson-review-board against this draft before promoting to live, or hand off to professor if you trust the draft."

References

• ${CLAUDE_PLUGIN_ROOT}/skills/lesson-builder/references/course-design.md — full lesson and module-guide templates
• ${CLAUDE_PLUGIN_ROOT}/skills/lesson-builder/references/assessment-patterns.md — three-part assessment structure with examples and scoring