Product Requirements Document (PRD): Learner Adaptive Loop

1. Overview & Vision

Hanoi Agents aims to provide a personalized, hyper-adaptive learning experience for K-12 students studying STEM and Computer Science. The Learner Adaptive Loop is the core loop that automates personalization by moving from self-reported data, to continuous assessment, to deep educational gap diagnosis, and finally to active learning intervention.

The loop is defined by four decoupled layers:

1. Learner Profile: Self-reported goals and preferences (Priors).
2. Learner Model: Dynamic capability and behavioral state (Posterior Estimates).
3. Learning Need Model: Deep educational diagnoses (Gaps, Needs, Retention, Transfer risks).
4. Learning Plan: Structured weekly action steps, activities, and success checkpoints.

---

2. User Personas

Learner (e.g., Lớp 7 preparing for "Tin học trẻ")

• Goals: Wants a clear, bite-sized weekly path to prepare for competitions without feeling overwhelmed.
• Needs: Needs to understand why they are stuck on a topic (e.g., recursion) and how to resolve the prerequisite blockages.

Parent / Teacher

• Goals: Wants to view the student's actual competencies, behavioral dedication (persistence), and current learning gaps.
• Needs: High-level visual reports validating the progress and the AI-driven remediation strategy.

---

3. The 4-Layer Progression Specification

Layer 1: Learner Profile (Self-Reported)

Allows learners to declare key constraints and targets. This establishes the initial prior beliefs of the learning engine.

• Grade: Academic grade (K12).
• Goal / Target: e.g., Competitive Programming ("Tin học trẻ"), Robotics, Web Development.
• Prior Experience: Self-declared familiar concepts (e.g., Scratch, Python Basic).
• Available Time: Allocated study minutes per day and days per week.
• Learning Style Preferences: Preference level for coding challenges vs. project-based works, and desired challenge level (Low, Medium, High).

Layer 2: Learner Model (System Trust)

Combines the static profile context with continuous assessment and behavioral logs to form a dynamic state representation.

• Capabilities: Overall mastery & confidence level across curriculum nodes (loops, variables, functions, matrices).
• Behavioral Telemetry:
  • Persistence: Willingness to keep trying questions after failing.
  • Average Attempts: Average tries per successful task completion.
  • Completion Rate: Ratio of completed quizzes to assigned ones.

Layer 3: Learning Need Model (Diagnosis)

Synthesizes the Target Goal Model (e.g., district competition guidelines) with the current Learner Model and prerequisite tree to isolate what must change.

• Need Classification:
  • Knowledge Gap: Low mastery on target competency.
  • Prerequisite Gap: Unresolved prerequisite node blocking advanced skills.
  • Practice Need: Strong theory understanding but low confidence/evidence.
  • Retention Need: Decay warnings indicating previously mastered skills are declining.
• Priority Level: High, Medium, Low based on severity and goal relevance.

Layer 4: Learning Plan (Action Plan)

A weekly plan mapped by the Planning Engine resolving the identified needs.

• Duration: Mapped typically across 8 weeks.
• Weekly Focus: Specific target skill/concept (e.g., Arrays, Functions).
• Target Activities: Practice quizzes, mini coding exercises, or hardware tasks.
• Success Checkpoints: Specific target mastery and confidence scores required to graduate from the week's focus.

---

4. Page & UI Wireframes Requirements

The feature is integrated under the route /adaptive (accessible via sidebar as Adaptive Loop) in a tabbed panel matching the 4 layers:

1. Profile Setup Tab:
   • Card forms for target goals, time sliders, prior experience checklists.
   • "Save Profile" action with automatic feedback.
2. Learner Model Tab:
   • Interactive telemetry gauges showing Persistence and Completion rate.
   • Grid display of mastered vs. developing skills.
3. Needs Analysis Tab:
   • Interactive list of detected educational gaps color-coded by priority (Red for High, Yellow for Med, Blue for Low).
   • Details panel explaining why the gap exists (pedagogical reason) and what evidence triggered it.
4. Learning Plan Tab:
   • Vertical timeline showing weeks 1-8.
   • Action items inside each week showing status (Completed, In Progress, Locked) and specific success criteria.