Alvorika/build-interactive-lesson

Build Interactive Lesson

Build one coherent teaching experience from planning through audit. Preserve freedom in narrative, examples, media, pacing, and justified technology choices while enforcing the phase gates, provenance, correctness, accessibility, secret safety, and honest review below.

Keep explanation primary

A lesson must remain coherent and substantially learnable when the learner does not touch any interactive control. Interaction may accelerate comparison, reveal causality, support practice, or deepen intuition, but it must not replace the core explanation.

Treat this as a pedagogical invariant, not a demand to disable JavaScript. Give the learner a readable no-click path through connected prose, default-state visuals, interpreted examples, boundaries, and transitions. Introduce every interaction, explain what to notice, and follow it with a takeaway.

Enforce the sequence

Complete Phases 0–9 in order. Iterate backward after testing when necessary, but never skip learner planning, approval, research, or teaching design on the way to production code.

Apply these gates:

1. Interview for missing learner, outcome, time/depth, and tutor decisions; present a plan and wait for approval unless autonomous defaulting was explicitly authorized.
2. Create explanation and media design before HTML, CSS, JavaScript, TypeScript, or application code.
3. Verify important claims against real sources; never fabricate access, claims, or citations.
4. Select the smallest coherent media and interaction set; give each selected interaction a named incremental value beyond the explanation.
5. Compute synchronized dynamic views from one canonical state when they represent the same model; do not invent state machinery for static media.
6. Default tutorMode to none; apply tutor state, provider, networking, and test requirements only to the selected mode.
7. Keep credentials out of source, URLs, events, public state, logs, exports, screenshots, audits, and knowledge artifacts.
8. Test accessibility, responsive behavior, domain correctness, and state consistency in proportion to risk.
9. Let pedagogical review fail independently of schema, browser, and accessibility checks; record unrun checks and limitations honestly.
10. Update the live design, contracts, and tests before completion whenever implementation materially deviates.

Do not substantially copy source prose, imagery, motion language, layout, palette, interaction choreography, or creator identity. Extract facts and general teaching moves, then synthesize an original lesson.

Load guidance just in time

Resolve paths relative to this SKILL.md.

• Read pedagogy.md before the learner interview, plan proposal, narrative design, explanations, examples, assessments, or scope decisions.
• Read interaction-design.md before choosing media, generating high-leverage candidates, running a disposable spike, designing shared state, or writing interaction contracts.
• Read research-and-provenance.md before research, source analysis, claim mapping, citation, or copyright-sensitive synthesis.
• Read accessibility-and-visual-review.md before implementation and again before browser and screenshot review.
• Read tutor-contract.md only when tutorMode is not none, an existing tutor is in scope, or external lesson-state integration is requested.
• Read artifact-contracts.md before creating artifacts, assigning IDs, passing phase gates, recording deviations, or writing the audit.
• Read eval-cases.md only when evaluating trigger behavior or forward-testing end-to-end lesson quality.
• Validate knowledge-pack.json with knowledge-pack.schema.json.
• Validate interaction-contracts.json with interaction-contracts.schema.json when selected dynamic interactions require contracts.
• Validate public window.lessonTutorContext snapshots with lesson-state.schema.json only when that standard interface is selected.

Treat reference examples as prompts for reasoning, never as a fixed interaction menu or page template.

Phase 0 — Inspect the request and existing work

1. Extract the topic, learner, observable goal, time and depth, language, supplied sources, tutor request, deployment constraints, technology constraints, and output constraints.
2. Inspect existing lesson files, code, screenshots, notes, tests, and audits before replacing anything.
3. When a golden example is supplied, inspect index.html, lesson-outline.md, sources.md, knowledge-pack.json, and audit-report.md when present. Extract its conceptual spine, sequencing, shared-state patterns, tutor interface, accessibility support, and audit discipline without copying its topic, formulas, controls, or visual identity.
4. Preserve good existing work unless a documented reason justifies changing it.
5. Do not ask for information already present in supplied material.

Phase 1 — Interview and optionally diagnose the learner

Proceed when audience, prerequisites, outcome, time/depth, and tutor mode are clear.

Ask one compact numbered round covering only missing information in these areas:

1. learner state and assumed prerequisites;
2. observable desired outcome;
3. available time and balance among intuition, formalism, proof, application, and practice;
4. tutor choice: none, light-byok, external-hook, or full-multi-provider.

Ask for a provider and deployment preference only when a tutor mode needs one. Never ask the user to paste an API key into the conversation. Do not ask for facts already supplied or discoverable in the repository.

When prerequisite uncertainty would materially change the explanation, ask 2–4 short concept or transfer questions in the conversation before generation. Test a consequential capability or confident misconception instead of self-rating alone. Map answers to prerequisite capsules, explanation depth, example choice, exercise level, or hint granularity. Do not automatically insert these diagnostic questions into the finished lesson.

Create learner-profile.json only when using diagnosis or personalization.

Phase 2 — Propose the lesson plan and wait

Present a concise proposal containing the learner model and assumptions, outcomes, central question, narrative spine, explanation depth, still visuals/tables/animations, candidate hero interaction, estimated explanation/observation/manipulation/assessment balance, deferred concepts, tutor mode/provider, and implementation risks or spike candidates.

Stop and request approval before production lesson code. Proceed without pausing only when the user explicitly authorizes autonomous execution, reasonable defaults, or no stop; record those assumptions. Treat “start now” as urgency, not automatic permission to omit learner planning.

Phase 3 — Research and map provenance

Use available web, browser, document, PDF, image, and connected-source tools. Cover source roles rather than chasing an arbitrary count:

• use authoritative or primary material for definitions, facts, formulas, and boundary conditions;
• use respected teaching material for sequencing and explanatory moves;
• use exercises or exams to inform assessment;
• use learner discussions to discover misconceptions, not as sole factual authority;
• analyze existing interactives for representation and interaction principles, not assets to clone.

Analyze visual sources for encoded entities, relationships, quantities, motion, manipulation opportunities, invariants, and failure boundaries when multimodal tools are available.

Create sources.md with stable source IDs, titles, URLs or paths, types, access dates, uses, limitations, and license/reuse notes. Create claim-ledger.json mapping every nontrivial claim to source IDs, confidence, output locations, and verification status. Paraphrase and synthesize; quote briefly only when necessary and attribute it.

Phase 4 — Design explanation and media before code

Create lesson-design.md before implementation. Include:

1. target learner and assumptions;
2. observable outcomes;
3. central motivating question;
4. prerequisite and diagnostic decisions;
5. target mental models and misconception map;
6. one narrative spine and a primary example or data story;
7. an explanation plan naming concepts needing sustained exposition, worked examples and their interpretation, and the no-click learning path;
8. a media plan covering useful still visuals, diagrams, tables, plots, sequential frames, and optional animation;
9. candidate hero interactions and the exact incremental value of each beyond the explanation;
10. assessment and transfer plan;
11. proportional time balance and reasons for major deviations from the default review range;
12. deferred concepts and boundaries;
13. accessibility, reduced-motion, and static-fallback plan;
14. tutor mode and provider/deployment decision;
15. an initially empty Interaction spike findings section and Implementation deviations section.

Build each major concept as a judged explanation unit: motivate the need, use a concrete instance or worked example, explain the mechanism in plain language, formalize at the right depth, add a purposeful representation, establish a boundary or confusion, and transition to the next idea. Use the relevant subset rather than seven mandatory fields.

Do not reduce the main teaching path to cards, labels, captions, and task instructions. Core ideas usually need connected explanatory paragraphs in a clear teacherly voice. Integrate definitions into a causal narrative, interpret worked examples, and keep indispensable explanation out of tooltips, tutor replies, wrong-answer feedback, and collapsed controls. Do not gate explanation behind a question unless deliberately eliciting a prior belief.

For concepts that may benefit from dynamic media, inventory objects, relationships, transformations, hidden state, learner-changeable causes, observable consequences, and spatial/temporal/topological structure. Compare 1–3 serious forms for high-leverage concepts, including a non-interactive alternative. Do not generate candidate tables for every minor concept.

Prefer one memorable hero interaction over several shallow panels. Use a slider only when a scalar continuum is genuinely the concept. Choose a still or stepped explanation when action adds no learning value. A configuration panel is not automatically an explorable explanation: first ask whether conceptual objects can transform, move, connect, route, group, or exchange information directly.

Phase 4.5 — Run a disposable interaction spike when needed

When a proposed hero interaction is novel, visually complex, central, or uncertain, build the smallest representative prototype under spikes/<candidate-id>/. Isolate one teaching question, use hard-coded data when useful, implement only the core action and response, and ignore production polish, tutor integration, and exhaustive tests.

Visually compare the spike with a still or stepped alternative. Record the hypothesis, manipulation or authored sequence, what became clearer, what stayed confusing, failure modes, accessibility implications, and a promote, revise, or discard decision in lesson-design.md. Remove discarded spike output from the final lesson.

Phase 5 — Select media and define proportionate contracts

Create and schema-validate interaction-contracts.json only for selected dynamic interactions. Omit it when no dynamic interaction needs a contract; do not contract static diagrams merely to fill a tree.

For every selected interaction, define a stable ID, learning question, target model, conceptual objects, learner action, sufficient derived representations and their purpose, expected insight, accessible fallback, input behavior, and acceptance evidence. Add canonical state, deterministic reset, invariants, browser paths, and tutor-visible state only when the interaction is stateful, risky, or connected to the selected tutor mode.

Require invariants only for real mathematical, state, conservation, agreement, or validity properties. Require browser paths for high-risk interactions and at least one representative end-to-end path for a genuinely interactive lesson when the environment supports it. Keep IDs stable where they add cross-artifact value.

Phase 6 — Build the knowledge pack

Create and schema-validate knowledge-pack.json. Include lesson metadata, audience, outcomes, scope, concepts, verified claims, sources, explanations, examples, misconceptions, relevant checks, and indexes. Include diagnostics, derivations, analogies, interactions, questions, hints, answers, tutor policies, and tutor state only when they serve the approved plan. Record tutorMode; default it to none.

Exclude credentials, provider configuration, secrets, fabricated support, and unverified claims presented as fact.

Phase 7 — Implement the lesson

Default to an original web lesson runnable from a local server without a proprietary backend. Choose among editorial prose, equations, original still illustration, annotated diagrams, tables, small multiples, plots, sequential frames, stepped or interactive animation, direct manipulation, and worked examples. Use the smallest medium set that explains each concept.

Use vanilla HTML, CSS, and JavaScript when sufficient. Choose SVG, Canvas, WebGL, D3, a framework, or another dependency when a high-value visual explanation would otherwise become brittle or unreasonably difficult; record the tradeoff in the design.

Produce index.html for a requested single-file lesson; otherwise prefer a maintainable small project. Keep design, provenance, contracts, knowledge pack, tests, tutor assets, and audit as separate logical artifacts even when bundling lesson CSS or code.

Implement semantic editorial hierarchy, connected readable prose, appropriately wider figures, precise computation, visible important state, non-color encodings, keyboard/pointer/touch support, reduced motion, narrow-mobile and high-zoom layouts, and no whole-page horizontal overflow. Use animation only to encode a named change or sequence; provide pause/replay or stepping when useful and a static or sequential-frame alternative. Brief purposeful non-looping autoplay is allowed when it is not essential.

When the selected tutor or external integration uses the standard public state interface, expose exactly:

window.lessonTutorContext = {
  version: "1.0",
  getState(),
  subscribe(listener)
};

In that profile, dispatch both lessonstatechange and lesson-state-change after meaningful state changes and validate secret-free snapshots against lesson-state.schema.json. Do not emit an empty Tutor API in tutorMode: none merely for compliance.

Phase 8 — Integrate only the selected tutor mode

Default to none. The lesson must remain complete without a tutor.

• none: create no tutor directory, settings, provider code, or tutor-specific state API.
• light-byok: consult the selected provider's current official documentation, record protocol/version and access date, and implement only that provider behind a small provider-neutral boundary. Keep direct credentials session-only by default; add a proxy only when requested or required.
• external-hook: expose only the documented context callback or event shape required by the user's existing backend; do not invent networking or settings UI.
• full-multi-provider: copy the bundled full tutor shell and preserve its OpenAI, Anthropic, Google Gemini, Mistral, OpenAI-compatible, proxy, redaction, cancellation, and security behavior.

Never ask for a key in conversation. For enabled tutor modes, make no network request until explicit Test or Send, keep model names configurable, redact errors, render safe text/Markdown, support cancellation and recovery, and provide a graceful offline or disabled state. Apply only the tests for the selected mode; do not copy five adapters into a one-provider lesson.

Phase 9 — Test, inspect, conduct pedagogical review, and audit

Concentrate tests on actual risk: independently check important formulas and examples; test state, reset, invariants, synchronization, and browser paths when declared; test tutor behavior only for the selected mode. A static diagram needs semantic and visual review, not invented state machinery.

Run the reusable structural validator:

python <skill-directory>/scripts/validate_lesson.py <lesson-directory>

Run the browser auditor when its environment is available:

node <skill-directory>/scripts/audit_browser.mjs <lesson-directory-or-url>

Inspect representative desktop and mobile screenshots when visual-inspection capability is available. Check occlusion, affordance, encoding integrity, formula/diagram agreement, motion, density, focus, tutor overlap, and static alternatives.

Create audit-report.md with separate Technical result: pass|fail|not-run and Pedagogical result: pass|fail|not-run lines, placing the latter under Pedagogical and self-study review. Review the no-click path, explanation completeness, narrative continuity, question density, media purpose, interaction leverage, proportionality, cognitive load, transfer evidence, and a cold-learner walkthrough. A pedagogical failure remains a failure even when schemas and browser checks pass.

When possible, ask a second reviewer to inspect the rendered lesson without reading the design first, summarize the central model, attempt the main example or transfer task, and identify a boundary. Label evidence honestly as design-reviewed, cold-walkthrough passed/failed, and actual learner study not run unless real learner testing occurred.

Never mark an unrun check as passed. Fix failures, update affected design and contracts, and rerun proportionate checks before delivery.

Deliver the artifact set

Produce this logical output:

<lesson-slug>/
├── lesson-design.md
├── learner-profile.json        # only with diagnosis or personalization
├── sources.md
├── claim-ledger.json
├── interaction-contracts.json      # only selected dynamic interactions
├── knowledge-pack.json
├── index.html
├── lesson.css / lesson.js          # when separated
├── lesson-assets/                  # media assets when used
├── tutor/                          # only when tutorMode != none
├── tests/
└── audit-report.md

Do not create empty directories to match the tree. Before handing off, confirm that IDs resolve, applicable schemas pass, claims have provenance, the no-click path teaches the central model, media serves named purposes, interactions add leverage, applicable dynamic views share state, stateful resets are deterministic, credentials cannot leak, links and controls work, deviations are recorded, and both audits distinguish evidence from assumptions.