# Universal Language Learning Framework (ULLF)

## 1. Core Principles

### 1.1 Les 5+1 Compétences Fondamentales
- **Reading (Lecture)** - Input passif écrit
- **Listening (Écoute)** - Input passif oral
- **Writing (Écriture)** - Output actif écrit
- **Speaking (Expression orale)** - Output actif oral
- **Composition** - Output structuré et académique
- **+1 Custom/Support** - Jour flexible pour combler manques ou absences

**Note** : Grammar/Structure est intégré dans chaque chapitre, pas de différenciation séparée

### 1.2 Hiérarchie d'apprentissage
```
Input (Reading + Listening) → Comprehension → Output (Speaking + Writing + Composition)
                    ↓
         Grammar (intégré dans chapters)
                    ↓
              Active Usage
                    ↓
            Games (3 per chapter)
```

### 1.3 Principes clés
- **Consistency over Intensity** - Daily practice > marathon sessions
- **Balanced Development** - Les 5 compétences progressent ensemble
- **Accountability** - Tracking + Exams réguliers
- **Spaced Repetition** - Review systématique pour retention
- **No Free Ride** - Tracking strict, pas de skip invisible
- **Game-Based Learning** - 3 jeux par chapitre pour rendre l'apprentissage interactif
- **Flexibility** - 1 jour/semaine libre pour combler les manques

---

## 2. Structure Temporelle

### 2.1 Cycle mensuel (4 semaines)
- **Semaines 1-3** : Learning + Review
- **Semaine 4** : Exam + Sit Rep + Planning

### 2.2 Rythme hebdomadaire
- **NEW content** : 2-3 chapters/semaine
- **REVIEW content** : 3-4 chapters/semaine
- **Total** : 6 chapters/semaine (1 par jour)
- **Jour 7** : FREE - Pour combler manques, absences, ou renforcer points faibles

### 2.3 Structure journalière (1-2h)
- **60-70%** : Nouveau contenu OU Review SRS principal
- **20-30%** : Reviews espacées multiples
- **10%** : Games (3 per chapter)

### 2.4 Assignation des jours
**Principe** : Chaque jour = 1 compétence fixe (6 jours/semaine)
- **Jour 1** : Speaking
- **Jour 2** : Composition
- **Jour 3** : Reading
- **Jour 4** : Listening
- **Jour 5** : Writing
- **Jour 6** : Custom/Support (review, catch-up, weak points)
- **Jour 7** : FREE (absence, manque, repos)

**Avantages** :
- Routine prévisible
- Mental load réduit
- Pas de decision fatigue
- Flexibilité intégrée pour la vie réelle

---

## 3. Content Structure

### 3.1 Types de ressources par compétence

**Reading :**
- Textes gradués par difficulté
- Vocab in context
- Comprehension questions
- Speed reading practice

**Listening :**
- Audio gradué par vitesse/accent
- Transcriptions disponibles
- Comprehension questions
- Shadowing material

**Writing :**
- Guided writing (structures imposées)
- Free writing (topics ouverts)
- Error correction exercises
- Style practice

**Speaking :**
- Dialogues/Scripts
- Pronunciation drills
- Topics discussion
- Recording/self-assessment

**Composition :**
- Structured academic writing
- Essay/text production
- Formal language practice
- Synthesis of multiple skills

**Grammar :**
- Intégré dans chaque chapter (pas de section séparée)
- Patterns/Structures enseignés en contexte
- Exercises de transformation dans chaque skill

### 3.2 Game Integration
**Chaque chapter inclut 3 jeux** pour renforcer l'apprentissage de manière interactive :

**Game 1 : Vocabulary Challenge**
- Matching game, flashcards interactives, ou quiz rapide
- Focus sur mémorisation du vocab du chapter

**Game 2 : Grammar/Pattern Practice**
- Sentence building, transformation puzzles
- Application des structures grammaticales

**Game 3 : Production Game**
- Role-play scenarios, writing challenges, listening puzzles
- Utilisation active du contenu dans un contexte ludique

**Integration dans classGen** : Les jeux sont générés en JSON et jouables via l'interface

### 3.3 Metadata des resources
Chaque chapter doit avoir :
```json
{
  "id": "unique-id",
  "skill": "reading|listening|writing|speaking|composition",
  "level": "beginner|intermediate|advanced",
  "estimated_hours": 1-3,
  "page_count": X,
  "density": "light|medium|dense",
  "vocabulary_count": X,
  "grammar_points": X,
  "games": [
    {"type": "vocabulary", "title": "...", "data": {}},
    {"type": "grammar", "title": "...", "data": {}},
    {"type": "production", "title": "...", "data": {}}
  ],
  "prerequisites": ["chapter-ids"],
  "learning_objectives": []
}
```

---

## 4. Spaced Repetition System (SRS)

### 4.1 Review Intervals
Quand un chapter est complété (Day 0), il entre dans le cycle :

- **Level 1** : Day 1 (review rapide - 10min)
- **Level 2** : Day 3 (review moyen - 20min)
- **Level 3** : Day 7 (review approfondi - 30min)
- **Level 4** : Day 14 (production active - 30min)
- **Level 5** : Day 30 (exam month - inclus dans exam)

### 4.2 Review Activities par Level

**Level 1** (Day 1) :
- Flash vocab
- Quick grammar recall
- Re-read/re-listen summary

**Level 2** (Day 3) :
- Redo quelques exercises
- Active recall (flashcards)
- Mini-production

**Level 3** (Day 7) :
- Production avec le contenu
- Speak/Write using material
- Identify weak points

**Level 4** (Day 14) :
- Integration avec nouveau contenu
- Compare/contrast concepts
- Advanced production

**Level 5** (Day 30) :
- Testé dans l'exam mensuel

### 4.3 SRS Tracking
Chaque chapter a un status :
```
NEW → L1 → L2 → L3 → L4 → L5 → MASTERED
```

---

## 5. Exam System

### 5.1 Principes
- **Frequency** : Monthly (semaine 4)
- **Coverage** : Tout le contenu des 3 dernières semaines
- **Format** : 1 exam par compétence (5 exams total)
- **Scoring** : /100 par exam
- **Purpose** : Accountability + Identify weak points
- **Generation** : 100% custom basé sur frameworks spécifiques (définis séparément)

### 5.2 Passing Criteria
- **>80%** : PASS - Maîtrise solide
- **50-80%** : DIFFICULTY - Révision nécessaire, points faibles identifiés
- **<50%** : CRITICAL - Révision intensive requise avant de continuer

### 5.3 Exam Framework Universel

Chaque exam suit cette structure générale :

**Part 1 : Recognition/Comprehension (30-40%)**
- Tester la compréhension passive
- Vocab, grammar, meaning

**Part 2 : Application (30-40%)**
- Utiliser le contenu dans exercises
- Transformation, fill-in-blank, etc.

**Part 3 : Production (20-30%)**
- Créer du contenu original
- Speaking/Writing libre avec contraintes

**Note** : Les frameworks détaillés par compétence (Speaking, Listening, Reading, Writing, Composition) seront définis dans un document séparé

### 5.4 Scoring Rubric Template
```
Grammar/Accuracy: /X
Vocabulary Usage: /X
Fluency/Coherence: /X
Comprehension: /X
Creativity/Natural Usage: /X
Total: /100
```

---

## 6. Tracking & Accountability

### 6.1 Daily Log
```
Date: YYYY-MM-DD
Day of Week: [Lundi-Dimanche]
Skill Focus: [Reading|Listening|Writing|Speaking|Grammar]
Chapter: [book-name] Chapter X
Type: [NEW|REVIEW-L1|REVIEW-L2|etc]
Time Spent: Xh Ymin
Speaking Practice: [Yes/No] - Xmin
Notes: [observations, difficulties, wins]
Streak: X days
```

### 6.2 Monthly Sit Rep
Généré automatiquement semaine 4 :

**Structure** :
- Chapters completed (by skill)
- Exam results (by skill + average)
- Progression metrics (streak, consistency)
- Strong points identified
- Weak points identified
- Next month plan

**Format** : .md + .html

### 6.3 Progress Metrics
- **Streak** : Jours consécutifs
- **Consistency** : % de jours avec practice
- **Balance** : Répartition entre les 5 compétences
- **Velocity** : Chapters/semaine
- **Retention** : Exam scores trend
- **Games Completed** : Nombre de jeux complétés par chapter

---

## 7. Adaptation par Langue

### 7.1 Variables à définir
Pour adapter ce framework à une langue spécifique :

```yaml
language:
  name: "Language Name"
  code: "xx-XX"

books:
  - id: "book-1"
    name: "Book Name"
    skill: "reading|listening|writing|speaking|composition"
    chapters: X
    pages_per_chapter: Y
    density: "light|medium|dense"

daily_schedule:
  day1: "speaking"
  day2: "composition"
  day3: "reading"
  day4: "listening"
  day5: "writing"
  day6: "custom-support"
  day7: "free"

rhythm:
  new_per_week: 2-3
  review_per_week: 3-4
  total_per_week: 6
  exam_week: 4

daily_time:
  total: "1-2h"
  new_content: "40-50%"
  speaking: "30-40%"
  reviews: "10-20%"

games_per_chapter: 3
```

### 7.2 Content Integration
Le système doit supporter :
- Import de content depuis books physiques
- Conversion en format digital (MD/JSON)
- Metadata extraction
- Game generation (3 per chapter)
- Exam generation (custom frameworks)

---

## 8. Tools & Ecosystem

### 8.1 Required Components
- **Content Storage** : Markdown files + JSON
- **Game Engine** : classGen ou similar
- **Tracking System** : Daily logs + metrics
- **Exam Generator** : Custom generation basée sur frameworks
- **Sit Rep Generator** : Automated reporting (.md + .html)

### 8.2 Workflow
```
Physical Book → Digitize (MD) → Structure (JSON) → Generate Games →
→ classGen Input → Study + Play Games → Track →
→ SRS Review → Monthly Exam → Sit Rep → Repeat
```

---

## 9. Success Criteria

### 9.1 Short-term (1 month)
- ✓ Consistency : >80% jours avec practice (min 24/30 jours)
- ✓ Balance : Les 5 compétences touchées
- ✓ Exam average : >80% (pass rate)
- ✓ Streak : >20 jours
- ✓ Games completed : 3 per chapter studied

### 9.2 Medium-term (6 months)
- ✓ All books 50% completed
- ✓ Exam average : >80% maintained
- ✓ Speaking confidence notable
- ✓ Can use language in target context
- ✓ No exams in CRITICAL range (<50%)

### 9.3 Long-term (12 months)
- ✓ All books 100% completed
- ✓ Exam average : >85%
- ✓ Fluent conversation in target language
- ✓ Can read/write/listen without major difficulty
- ✓ All chapters at MASTERED status in SRS

---

## Version History

- v1.0 (2025-10-29) : Initial framework creation
- v1.1 (2025-10-29) : Corrections post-feedback
  - Changed 4+1 to 5+1 skills (added Composition, Custom/Support day)
  - Grammar integrated into chapters (not separate)
  - 6 days/week + 1 FREE day
  - Added 3 games per chapter requirement
  - Exam passing criteria: >80% pass, 50-80% difficulty, <50% critical
  - Removed XP/Achievement gamification
  - Exam generation 100% custom based on frameworks