Study plan distribution front-loads the first unit and gives every lesson of a unit the same material slice

[arqo123]

Environment

• Self-hosted instance, FreeLingo v1.8.45 (Docker Compose)
• Course: German (Deutsch), level A2, default plan shape (12 weeks x 4 days)
• Everything below comes from calling distribute_units() directly, so it is independent of the LLM, the gateway and the model in use

What happens

The plan grid for 12w x 4d has 48 slots — 47 lessons plus the completion test. German A2 has 8 units. The distribution is:

unit	lessons
a2-unit-1 Perfekt mit haben und sein	15
a2-unit-2 … a2-unit-7	5 each
a2-unit-8 A2 Wiederholung	2
completion test	1

So the learner spends weeks 1–4 on a single grammar topic — Perfekt mit haben und sein - Lektion 1 through Lektion 15, cycling grammar → vocabulary → reading → writing → review three times — before ever meeting Präteritum. The final unit, whose whole purpose is recapping the level, is truncated to 2 lessons and loses its reading, writing and review slots.

This is a follow-up to #295 / #300. The prompt-level fix landed and works in its own layer, but the lessons still converge, because of a second cause described below: every one of those 15 lessons is generated from a byte-identical input.

Cause 1 — the advance guard front-loads all surplus onto the first unit

backend/app/data/curriculum.py:193-198:

type_index += 1
if type_index % len(lt_list) == 0 and unit_index < len(units) - 1:
    remaining_slots = lesson_slots - slot - 1
    remaining_units = len(units) - unit_index - 1
    if remaining_slots <= remaining_units * len(units[unit_index + 1].lesson_types):
        unit_index += 1

The guard advances to the next unit only once the remaining slots have shrunk to roughly one cycle per remaining unit. At the start remaining_slots = 42 and remaining_units * 5 = 35, so the condition is false and the loop keeps cycling unit 1's lesson types. Every surplus slot (47 slots for 8 x 5 = 40 natural lessons) therefore lands on the first unit, and the tail is squeezed.

The same guard also drops units entirely in the deficit case: at 4w x 6d (23 slots) units 6, 7 and 8 get zero lessons, so the learner completes "A2" without ever meeting Nebensätze or Relativsätze — structures the A2 completion test itself covers.

Cause 2 — every lesson of a unit gets the same fixed slice of the unit's material

backend/app/data/curriculum.py:186-189:

"grammar_points": (unit.grammar_points[:2] if unit.grammar_points else []),
"vocabulary_set_ids": (unit.vocabulary_set_ids[:1] if unit.vocabulary_set_ids else []),

The slice is constant for every slot of the unit. For a2-unit-1 all 15 lessons receive:

grammar_points     = ['perfekt-mit-haben', 'perfekt-mit-sein']
vocabulary_set_ids = ['erfahrungen_de_a2']
distinct (grammar_points, vocabulary_set_ids) tuples across the 15 lessons: 1

The generator is asked fifteen times for a different lesson on identical inputs. The sibling-context block from #300 tells the model not to repeat itself but gives it no new material to move to, which is why the duplication survived that fix.

The truncation also means a large part of every curriculum is never taught. German A2, counting only real lessons:

grammar points reaching a lesson: 14 / 22
never in any lesson: adjektivdeklination-null, nebensatz-obwohl, nebensatz-wenn,
  partizip-ii, personalpronomen-akk-dat, praeteritum-modalverben,
  vergleich-als-wie, wortstellung-nebensatz
vocabulary sets used: 8 / 15

a2-unit-6 Nebensätze declares 5 grammar points and teaches 2. a2-unit-8 A2 Wiederholung declares 12 and teaches 2.

This is not German-specific. Across all shipped curricula at the default plan shape:

language	grammar points reaching a lesson	worst first-unit pile-up
en-GB	69/83 (83%)	20 lessons (C2 unit 1)
de-DE	79/118 (66%)	15 lessons (A1 unit 1)
es-ES	84/137 (61%)	15 lessons (A1 unit 1)
fr-FR	84/124 (67%)	15 lessons (A1 unit 1)
it-IT	84/132 (63%)	15 lessons (A1 unit 1)
pt-PT	83/132 (62%)	15 lessons (A1 unit 1)
ja-JP	84/130 (64%)	6 lessons (A1 unit 1)
ko-KR	86/126 (68%)	6 lessons (A1 unit 1)
zh-CN	85/126 (67%)	7 lessons (B2 unit 1)

Side effect: the unit drawer promises material the course never teaches

frontend/src/components/plan/UnitDrawer.tsx:89 renders unit.grammar_points — all four for a2-unit-1, including partizip-ii and perfekt-vs-praeteritum. No lesson of that unit ever receives those two, so the drawer lists them as covered grammar while nothing in the unit covers them.

Reproduction

from app.data.curriculum import get_curriculum_units, distribute_units
from collections import Counter

units = get_curriculum_units("A2", "de-DE")
slots = distribute_units(units, 12, 4, "de-DE")
print(Counter(s["unit_id"] for s in slots))

lesson_slots = [s for s in slots if s["unit_id"] != "completion-test"]
print(len({(tuple(s["grammar_points"]), tuple(s["vocabulary_set_ids"]))
           for s in lesson_slots if s["unit_id"] == "a2-unit-1"}))   # -> 1

all_gp = {g for u in units for g in u.grammar_points}
used = {g for s in lesson_slots for g in s["grammar_points"]}
print(len(used), "/", len(all_gp), sorted(all_gp - used))

There are currently no tests over distribute_units() — grep -r distribute_units backend/tests/ returns nothing — which is how both behaviours survived.

Relation to #295 and #300

#295 diagnosed this as a prompt problem and #300 fixed the prompt. That was correct as far as it went, but the issue looked one layer too high. Two things I got wrong there and want to correct explicitly:

• The environment block recorded "Unit 1 (15 lessons)" as a fact and never questioned it. Fifteen lessons on one grammar point is the larger half of the problem.
• The third bullet of "Proposed direction" — "Optionally partition vocabulary_set_ids and example themes across the unit so lessons draw from different slices instead of the whole set every time" — was the load-bearing item, and I marked it optional. It also understated the case: lessons do not draw from the whole set every time, they draw from a fixed one-element slice of it.

Proposed direction

Rewrite the allocation in distribute_units():

1. Rotate the material slices per lesson. Lesson k of a unit takes a window of ~2 grammar points starting at (k * 2) % len(points) and vocabulary_set_ids[k % len(sets)]. Cheapest change here and on its own it removes the identical-input problem; every declared grammar point and vocabulary set then reaches at least one lesson.
2. Allocate slots evenly, cap the block, never drop a unit. Block width w = clamp(lesson_slots // n_units, 3, 6); leftovers go to a consolidation phase at the end rather than widening any block, because a 7th consecutive lesson on one unit starts repeating regardless of slice rotation. In the deficit case thin every unit to 3 slots instead of dropping the tail — a plan that never reaches Relativsätze is a curriculum integrity problem, not a scheduling compromise.
3. Interleave spaced revisits instead of an in-block review. A review lesson the day after the material adds little; displaced in time it is retrieval practice. A block of [grammar(N), vocabulary(N), reading(N), revisit(N-2), writing(N), revisit(N-1)] caps the run on one topic at 3, and gives every unit revisits at expanding intervals (~6 and ~10 slots later, then consolidation) with no per-item bookkeeping. A revisit slot is an ordinary slot — unit_id of the revisited unit, lesson_type: "review", a rotated slice of its points — so the lesson generator needs no changes at all.
4. Surplus becomes consolidation, never more same-type lessons. Mixed review across earlier units plus free production, which is also where the final "Wiederholung" unit belongs; generating grammar and vocabulary lessons for a review unit is incoherent as it stands.

One interaction worth flagging: revisit slots carry lesson_type: "review", which build_grammar_exercise_ratio() (added in #300, following your review) maps to 70% grammar exercises. That is probably right for a revisit, but it should be a deliberate choice rather than a side effect.

Happy to open a PR for this if the direction looks right. My inclination is to do 1 and 2 first as the actual fix, then 3 and 4 separately, so the correctness change and the sequencing change can be reviewed apart.

Out of scope here

• Lesson titles number globally (type_index never resets per unit), so unit 2 starts at "Lektion 16". Cosmetic, separate.
• Whether the assessment result should influence the plan at all — Assessment results and lesson performance never influence the study plan: is learner-responsive sequencing a direction you want? #317, since that is a direction question rather than a defect.
• The "unexpected error" when opening a later lesson of a unit out of sequence, reported in Lessons within the same unit are near-duplicates: generation prompt has no sibling-lesson context and no per-type differentiation #295, is still unaddressed and still blocks inspecting later lessons directly. Possibly related to Generate exercise does not wait until LLM is finished #310.

[artcc]

Thank you for the exceptionally detailed report. I have now traced this through the current codebase, reproduced the distributions directly, checked the lesson-generation consumer, and reviewed the interaction with the plan UI, competencies, and completion test.

Overall verdict

The primary allocation defect is valid and serious. The current allocator front-loads early units, truncates the tail, and can omit later units entirely. However, the second proposed cause does not match the runtime generation path: the [:2] and [:1] values are persisted in the generated-plan JSON, but they are not the values passed to generate_lesson().

The relevant code is unchanged between v1.8.45 and the current v1.8.50 checkout, so the allocation problem still applies.

Confirmed: the default German A2 distribution

I reproduced the exact 12 x 4 result:

a2-unit-1: 15
a2-unit-2: 5
a2-unit-3: 5
a2-unit-4: 5
a2-unit-5: 5
a2-unit-6: 5
a2-unit-7: 5
a2-unit-8: 2
completion-test: 1

Unit 1 occupies W1D1 through W4D3 and cycles through its five lesson types three times. Unit 8 receives only grammar and vocabulary, losing its reading, writing, and review slots.

Your analysis of the guard at backend/app/data/curriculum.py:193-198 is correct for this curriculum. It keeps repeating the current unit until the remaining capacity is approximately one declared cycle per remaining unit, so all surplus lands at the front and the final unit is squeezed.

There are two additional allocator weaknesses:

• type_index is global, so with heterogeneous lesson_types lengths a unit can start partway through its own type cycle.
• The remaining-capacity calculation multiplies every remaining unit by the lesson-type count of only the next unit, which is incorrect when later units have different widths.

Confirmed: units disappear in shorter plans

The reported 4 x 6 result is also correct, with unit 5 additionally truncated:

[5, 5, 5, 5, 3, 0, 0, 0]

The currently offered intensive option in the frontend is actually 4 x 5, not 4 x 6. German A2 is worse there:

[5, 5, 5, 4, 0, 0, 0, 0]

I also checked all 10 target languages, 6 CEFR levels, and the 4 plan shapes currently offered by the frontend:

• 4 x 5: all 60 language/level combinations omit at least one unit.
• 8 x 5: 26 of 60 omit at least one unit.
• 12 x 4: 5 of 60 omit at least one unit.
• 16 x 3: the same 5 combinations omit a unit because it has the same 48-slot capacity as 12 x 4.
• At the default 12 x 4 shape, 40 of 60 combinations have a unit-count imbalance greater than one lesson.

The five default-shape combinations that omit unit 8 are:

en-US A2
en-US B2
zh-CN B2
zh-CN C1
zh-CN C2

This is more than a pedagogical sequencing issue. The normal UI can become impossible to complete:

• Unit competencies are created only when a lesson belonging to that unit is completed.
• The frontend unlocks the level test only when every static unit has competency >= 0.8.
• A unit with no scheduled lessons cannot acquire plan-scoped competency through the normal lesson flow and therefore remains at zero.

The timeline itself can reach its final day, but the normal level-test UI remains locked. The backend level-test questions endpoint currently checks ownership rather than enforcing the frontend competency gate, so the two layers are also inconsistent here.

Correction: the persisted slices are not generation input

The slices you identified do exist in distribute_units():

"grammar_points": unit.grammar_points[:2],
"vocabulary_set_ids": unit.vocabulary_set_ids[:1],

They are copied into DayPlan and persisted in study_plans.generated_plan. However, GET /today does not read those fields when generating a lesson.

At backend/app/routers/study_plan.py:250-260, the router resolves the static curriculum unit again and assigns the complete lists:

grammar_points = cu.grammar_points
vocabulary_set_ids = cu.vocabulary_set_ids

Those complete lists are then passed to generate_lesson() at lines 275-287.

For German A2 unit 1, every generated lesson is therefore offered all of this material:

grammar_points:
- perfekt-mit-haben
- perfekt-mit-sein
- partizip-ii
- perfekt-vs-praeteritum

vocabulary_set_ids:
- erfahrungen_de_a2
- reisen_de_a2

This means the following conclusions in the report do not hold for the runtime path:

• 14 / 22 is not the number of German A2 grammar points reaching generation.
• 8 / 15 is not the number of vocabulary sets reaching generation.
• Unit 6 is not restricted to its first 2 of 5 grammar points.
• Unit 8 is not restricted to its first 2 of 12 grammar points.
• partizip-ii and perfekt-vs-praeteritum do reach every generated unit-1 lesson.
• The cross-language coverage table measures serialized plan metadata, not the arguments used by the lesson generator.

The cross-language table also omits the shipped en-US curriculum, so it is not complete as an “all shipped curricula” inventory.

The persisted slice fields are effectively dormant metadata in the current runtime. Rotating them only inside distribute_units() would therefore be a no-op unless /today were also changed to make per-slot material authoritative.

The generator inputs are not byte-identical

All lessons of a unit do currently receive the same complete grammar and vocabulary lists. That can still contribute to convergence when a unit is incorrectly expanded to 15 lessons, and the over-allocation is a valid reason for duplication to remain possible after #300.

However, the complete calls are not identical. They differ by:

• lesson_type
• lesson title/topic
• week and day
• sibling-lesson context accumulated from already generated lessons of the same unit

The sibling block from #300 explicitly asks for different aspects, examples, settings, vocabulary use, and common traps. Therefore, the direct distribute_units() reproduction proves that the stored slot metadata is identical, but it does not prove that the prompt passed to the model is identical.

There is also an important distinction between material being supplied and material actually being taught. The current runtime supplies all declared material for every scheduled unit, but the prompt does not guarantee that every item will appear in generated output. A unit with 12 grammar points and only 2 lessons can still have real coverage gaps; they just cannot be inferred from the dormant [:2] fields.

Unit drawer

The drawer does display the full static unit.grammar_points list. The specific German A2 claim that partizip-ii and perfekt-vs-praeteritum reach no lesson is not correct because both are passed to generation.

There is nevertheless a valid semantic concern: the label says grammar is “covered” based on the static curriculum declaration, not based on persisted generated content or grammar_refs.

There is an even clearer manifestation in omitted units. The plan page renders all static units even if a unit has no scheduled slots, falls back to unit.lesson_types.length as its displayed lesson count, and the drawer displays the full grammar list followed by “no lessons.” That can promise material which the generated plan cannot teach.

Assessment/completion-slot inconsistency

One adjacent issue surfaced during the trace. The synthetic completion-test slot appended by distribute_units() is not the actual level test flow.

On that scheduled day, /today cannot resolve unit_id="completion-test" to a static curriculum unit, so it generates an ordinary review lesson with empty grammar and vocabulary context. The real 20-question level test is a separate frontend pseudo-unit and backend assessment endpoint, and that endpoint receives all static material for the level.

This should be handled separately, but it matters when deciding whether the allocator should continue reserving one schedule coordinate for completion-test.

Assessment of the proposed implementation directions

1. Rotating slices

The general idea may be useful if per-slot material is intentionally made authoritative, but it is not the cheapest standalone fix today because the consumer ignores the fields.

The proposed rotation also does not guarantee complete coverage when a unit has more material than its allocated windows can expose. For example, 2 lessons with 2 grammar points each cannot cover a 12-point review unit.

For the initial allocation fix, I would keep the current complete-unit generation context and separately decide whether slot-level slices should become authoritative or be removed as dead metadata.

2. clamp(..., 3, 6) and never dropping a unit

Never dropping a unit is the right invariant whenever there is capacity for at least one slot per unit. A universal minimum of 3 is not feasible, however:

8 units x 3 lessons = 24 teaching slots
4 x 6 leaves 23 teaching slots after reserving the test
4 x 5 leaves 19 teaching slots after reserving the test

The request schemas also currently accept arbitrary integer dimensions without positive bounds or supported-pair validation. Inputs with too little capacity need to be rejected rather than silently violating an impossible minimum.

3. Interleaved revisits

This is pedagogically plausible but should be a separate sequencing feature, not part of the correctness patch.

The current application has contiguous-unit assumptions. In particular, lesson completion treats a different next unit_id as evidence that the current unit is complete and may show the user-review prompt. Interleaving an earlier unit would create false unit-completion transitions unless that state model is changed.

The fixed proposed block also needs to account for all supported modalities, including listening and speaking in the Asian-language curricula.

4. Consolidation phase

Every shipped level already has a final review/consolidation unit in its static curriculum. The current CurriculumUnit and slot schemas also represent only one unit_id, so a mixed review across multiple earlier units cannot be represented cleanly without a model and prompt-context change.

Whether grammar or vocabulary lesson types are appropriate inside the authored final review units is a curriculum-design question rather than an allocator defect.

Review ratio

Your observation about review mapping to 70% is correct. In the current implementation that mapping is explicit and tested, rather than an accidental fallback. It is suitable for existing unit review lessons, but a future cross-unit or free-production consolidation type may need separate semantics.

Recommended minimal correction

I think the safe first patch should be limited to deterministic allocation, validation, and tests.

A quotient/remainder allocation across contiguous unit blocks would produce, while preserving the currently reserved final slot:

4 x 5:  [3, 3, 3, 2, 2, 2, 2, 2]
8 x 5:  [5, 5, 5, 5, 5, 5, 5, 4]
12 x 4: [6, 6, 6, 6, 6, 6, 6, 5]
16 x 3: [6, 6, 6, 6, 6, 6, 6, 5]

That would:

• schedule every unit for all four currently supported frontend plans;
• limit the count difference between units to one;
• preserve prerequisite-friendly contiguous blocks;
• cap default-plan runs at six lessons;
• give the final consolidation unit meaningful capacity;
• avoid introducing revisit or cross-unit semantics in the bug fix.

The type index should be local to each unit so every block starts from the first declared lesson type rather than inheriting a global modulo position.

The exact placement of quotient remainders is a small product decision. If preserving a full cycle for the final consolidation unit is more important than giving the extra slot to the first units, the remainder ordering can reflect that explicitly.

Inputs should at least require positive weeks/days and reject plans whose teaching-slot count is lower than the unit count. Restricting the API to the four frontend-supported pairs would be a separate product/API decision.

Tests needed

There are currently no direct tests over distribute_units(). The existing study-plan tests verify plan creation and sibling context but do not assert distribution or which material source is authoritative.

The fix should add coverage for:

• all 10 target languages;
• all 6 CEFR levels;
• all 4 frontend-supported plan shapes;
• every unit appearing when capacity permits;
• per-unit counts differing by at most one;
• exact output length and unique week/day coordinates;
• the final reserved coordinate;
• local lesson-type cycling;
• heterogeneous British English curricula;
• seven-type Chinese B2-C2 curricula;
• invalid/non-positive dimensions and insufficient capacity;
• a router-level assertion documenting whether full-unit or per-slot material is passed to generation.

Existing plans

One final migration consideration: generated_plan is persisted as JSON when a study plan is created. Changing distribute_units() will fix new plans only. Existing plans, including short plans with omitted units, will retain their old schedule unless we explicitly provide a regeneration or migration strategy. Rewriting in-progress plans is risky because lesson titles, generated lesson rows, progress, and competencies are already tied to the stored schedule, so this needs an explicit compatibility decision.

In short: the allocation diagnosis is confirmed and should be fixed with high priority. The slice/coverage diagnosis needs correction because it follows a persisted field that the runtime generator does not consume. I would keep the first PR narrowly focused on even allocation, local type cycling, validation, and tests, then handle material partitioning, revisits, consolidation semantics, and the completion-test mismatch separately.