Skip to content

Design and implement adaptive learning with learner feedback, stacked on the revamp #49

Open

Description

@durasj

Problem and intended outcome

The revamped Chips and Code journey deliberately assumes almost no prior knowledge. That works for curious beginners, but learners studying the subject at school/university, or with relevant experience, may find familiar material repetitive. Knowledge will vary by topic; academic level alone is not a useful placement rule.

Design and implement a learning path that lets people bypass familiar material and obtain suitable guidance/challenge as they progress, while preserving the approachable beginner experience. This issue is an agent handover: investigate the problem and alternatives carefully, document the decision, then implement and verify the chosen approach. It is not just a request for a design document.

Required base: stack on the revamp

Depends on revamp PR #47, currently an open draft.

Confirmed user direction

  • Serve both people starting with essentially zero knowledge and people who already understand some topics.
  • Do not hold someone back with compulsory basics they know; binary was the user's example.
  • Explore a mix of learner choice and adaptation, rather than assuming that a fully automatic system is the answer.
  • Do not use elapsed time, completion speed, dwell time, or inactivity to judge understanding, difficulty, or the next learning recommendation. This concerns learner assessment; operational timeouts and simulator clock cycles are unaffected.
  • The user suggested asking something like “Was this too easy?” and responding to that feedback. The exact wording, frequency, and resulting change need design work.
  • Preserve the revamp's minimal, mature visual design and coherent Learn / Tools / About experience.

No particular onboarding screen, diagnostic algorithm, mastery threshold, or set of separate tracks has been approved.

Current implementation to investigate

These entry points were inspected at the commit above:

Area Starting points Relevant behavior
Beginner journey src/routes/learn/+page.svelte, src/lib/game/Game.svelte, SignalIntro.svelte Intro and mission progression; next incomplete mission is selected.
Gate challenges src/lib/game/missions.ts, MissionWorkbench.svelte, circuit.ts Mission prerequisites, available components, hints, guided wiring, Visual/Code/Split modes, truth-table validation.
Projects 1–6 src/lib/course/data.ts, Path.svelte, Chapter.svelte Buses, arithmetic, memory, machine language, architecture, assembler; chapter and task navigation already allow direct selection.
Verification src/lib/course/verify.ts, sandbox.ts Hardware/assembly checks and isolated learner-assembler execution.
Supporting explanations src/lib/learning/, src/routes/learn/reference/ Full reading and concept explanations should remain available at any entry point.
Regression coverage cypress/e2e/learn.cy.ts, game.cy.ts, part-one.cy.ts, accessibility.cy.ts Extend the existing learner journeys and accessibility checks.

Beginner progress and later course progress currently live in separate local-storage models. Game.svelte reads chipsandcode.progress.v1 with a legacy fallback and a separate signal-intro flag. Chapter.svelte reads courseProgressKey and stores per-task drafts. Inspect the complete persistence and prerequisite behavior before proposing a unified recommendation model. Do not lose existing work or mark skipped tasks as verified.

The revamp includes guided content through Project 6 and six tool types. This feature should work within that scope; extending the curriculum beyond the assembler is not required.

Design investigation before implementation

Produce a concise decision record grounded in the current code and relevant learning-design evidence. Then implement; do not stop at recommendations.

  1. Entry and agency: Compare self-selected starting points, optional topic checks, challenge-first entry, and performance-based recommendations. The previously discussed “Start from scratch / Find my starting point / Choose a topic” is a candidate, not prescribed UI. Keep direct navigation and easy recovery.
  2. What adapts: Define what “harder” and “easier” mean for each relevant layer: guidance, repetition, explanation depth, challenge complexity, or next topic. Avoid merely hiding explanations or jumping over conceptual prerequisites.
  3. Feedback: Explore an occasional, dismissible “too easy / about right / need more help” interaction or a better alternative. Explain what changes and let the learner reverse it. Do not add an interruption after every small action.
  4. Evidence and uncertainty: Treat stated familiarity and difficulty preference separately from demonstrated understanding. Evaluate whether different task variants are needed. One passing solution, one failure, hints, or an editor error should not automatically establish a broad ability level. No timing inputs.
  5. Topic-level gaps: A learner may know binary but not Boolean logic, or code comfortably but lack hardware knowledge. Identify prerequisites, offer focused refreshers, and avoid one permanent beginner/advanced label.
  6. State and scope: Define the smallest useful state model, recommendation rules, persistence/migration strategy, and reset/override behavior. Account for reloads, unavailable storage, repeat visits, and existing saved drafts. Justify any additional infrastructure.
  7. Reliability: Distinguish a recommendation from a claim of mastery. Document what the first version can establish and what would require learner testing. Prefer a comprehensible first version over unsupported claims of accurate personalization.

A research starting point is Khan Academy's skill-level mastery model. It is a comparison to investigate, not proof that the same rules suit circuit construction.

Acceptance and verification

  • A new learner can take the existing foundational journey without compulsory assessment or additional onboarding barriers.
  • A learner can bypass familiar basics and choose a relevant topic without pretending skipped work was completed.
  • Learner difficulty feedback has a clear, documented effect on guidance or the recommended challenge; it is optional and reversible.
  • Decisions use documented topic-level signals and never use learner timing/speed.
  • Missing prerequisites can be revisited without restarting the whole journey or losing work.
  • Recommendations preserve access to hints, full explanations, and manual topic navigation.
  • Old progress and drafts survive; choices and new progress behave correctly after reload and when storage is unavailable.
  • UI remains usable with keyboard and assistive technology and at the revamp's small-screen layouts; Visual/Code/Split workflows and Tools continue working.
  • Tests cover novice entry, experienced entry, skipping, feedback changes, mistaken placement/recovery, persistence/migration, and identical decisions for identical non-time inputs regardless of elapsed time.
  • Run the repository's applicable type, unit, production-build, and browser checks. Review desktop/mobile results. The existing PR's reported 494 unit and 56 browser tests are a historical regression baseline, not a substitute for running checks on the new changes.
  • Deliver a stacked implementation PR linking this issue and Build the computer journey through assembler and add the full Nand2Tetris tool suite #47, with the design rationale, alternatives considered, test evidence, and remaining learning-effectiveness limitations.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions