12 KiB
Curriculum specification
Purpose
This document defines the functional behaviour of a perpetual AI-generated learning curriculum. It is implementation-agnostic — no assumptions are made about programming language, framework, database, or AI provider. Any system that satisfies these functional requirements is a valid implementation.
Concepts
Knowledge base (KB) The source of truth for all learning content. Organised as a two-level hierarchy: Themes (broad subject areas) containing Topics (specific concepts). Topics carry metadata that informs curriculum sequencing.
Theme A broad subject area. One Theme = one weekly session. A Theme contains one or more Topics.
Topic An atomic unit of knowledge within a Theme. Carries:
- a complexity weight (1–5 scale, 1 = introductory, 5 = advanced)
- a difficulty label (introductory / intermediate / advanced)
- relationships to other topics: prerequisite, related, contrast
Curriculum A versioned 26-week schedule mapping one Theme per week. The curriculum is generated by AI from the KB, not manually authored. Admins review and finetune it before it is applied.
Curriculum version Each generation produces a new version. Only one version is active at a time. Previous versions are retained for audit purposes.
Cycle One full pass through the 26-week curriculum. After completing week 26, an employee begins cycle 2. Cycles continue indefinitely.
Employee curriculum state Tracks each employee's position: current cycle, current week, start date, and which curriculum version they are on. Employees have independent start dates — there are no cohorts.
Completed week A week where the employee has recorded at least one session completion. Completed weeks are immutable — no regeneration or version change may alter a completed week's record.
Functional requirements
1. Curriculum generation
The system must be able to generate a 26-week curriculum from the current published KB.
Trigger conditions:
- Manually by an admin
- Automatically when new Topics are published to the KB
Inputs to the generator:
- All published Themes, each with their ordered Topic list
- Per Topic: title, complexity weight, difficulty, prerequisite relationships
- If regenerating: reason for regeneration
Generation process:
Step 1 — Pre-process topic order within each Theme Before any AI involvement, resolve the order of Topics within each Theme using their prerequisite relationships. Build a directed graph of prerequisite edges and apply a topological sort. The result is an ordered topic list per Theme where prerequisites always precede dependent Topics. If a cycle is detected in the graph (which should not occur in a well-formed KB), fall back to ordering by complexity weight ascending.
This pre-processing offloads prerequisite reasoning from the AI — the AI receives already-ordered topic lists and focuses only on Theme sequencing across weeks.
Step 2 — AI sequences Themes across 26 weeks The AI receives the pre-processed KB snapshot and produces a 26-week schedule. The AI must follow these sequencing rules:
- Every Theme must appear at least once across the 26 weeks
- Themes with more Topics may span multiple weeks or recur within the 26 weeks
- Foundational Themes precede dependent ones
- Complexity increases progressively: introductory Themes in the first half, advanced Themes in the second half
- If the KB contains more Topics than 26 weeks can cover in depth, prioritise breadth in cycle 1 — every Theme covered, key Topics per Theme
- Each week slot has an estimated session duration (15–45 minutes)
- Each week slot includes a one-sentence rationale explaining its position
Output: A draft 26-week schedule with one Theme and an ordered Topic subset per week, estimated duration per week, and a rationale per week.
Validation: All Theme and Topic references in the generated schedule must resolve to existing published KB entries. Any reference that does not resolve must cause the generation to be retried or rejected — never persisted.
2. Admin review and confirmation
A generated curriculum is always a draft first. It is not applied to any employee until an admin explicitly confirms it.
Admin capabilities before confirmation:
- Preview the full proposed 26-week schedule
- View the rationale for each week's Theme assignment
- Reorder weeks (swap Theme assignments between weeks)
- Add or remove Topics from a week's Topic subset
- Annotate any week with free-text notes
- Compare the proposed schedule against the currently active version
Confirmation: When admin confirms, the new version becomes active and is applied to all employees whose current week falls within the regenerated range (see section 4 — versioning).
Rejection: If admin rejects the draft, it is discarded and no changes are applied.
3. Perpetual cycling
The curriculum runs indefinitely. After an employee completes week 26, cycle 2 begins automatically on the latest active curriculum version.
Cycle 2 and beyond are not identical to cycle 1. The generator must vary subsequent cycles to reinforce rather than repeat. When generating a cycle 2+ schedule for an employee, the generator receives additional input:
- Which micro learning types the employee has used across their history
- Which micro learning types the employee has not yet used
- Which Topics the employee engaged with minimally (completed only the minimum required interaction)
The generator uses this input to:
- Vary the Theme sequence from the previous cycle
- Surface underused micro learning types as recommended formats
- Schedule low-engagement Topics earlier in the new cycle to give them more visibility
4. Versioning and version transitions
One active version at all times. Previous versions are archived, not deleted.
Completed weeks are frozen. When a new curriculum version is applied, only future unstarted weeks are updated. Any week the employee has already started or completed retains its original content. The boundary is the employee's current week at the moment the new version is applied.
Version transition logic: When a new version is confirmed:
- For each active employee: identify their current week N
- Weeks 1 through N-1 are already completed — untouched
- Week N onward is replaced with the new version's schedule
- The employee continues from week N on the new version seamlessly
Regeneration triggers: Two events should prompt a regeneration:
- New Topics are published to the KB (new content available for scheduling)
- Admin manually requests regeneration
In both cases, the new version must be previewed and confirmed by an admin before being applied. Regeneration is never automatic.
5. Employee curriculum state
Each employee has an independent curriculum state:
| Attribute | Description |
|---|---|
| Current cycle | Which pass through the 26-week schedule (starts at 1) |
| Current week | Which week within the cycle (1–26) |
| Start date | When this employee began their curriculum (rolling) |
| Active version | Which curriculum version the employee's future weeks draw from |
State transitions:
- Week completion: current week increments by 1
- Week 26 completion: cycle increments by 1, current week resets to 1, active version updates to latest, cycle variant generated
- Version applied: active version updates for weeks not yet started
6. Coverage guarantee
The curriculum must cover the entire published KB within one cycle. Every published Theme must appear at least once in the 26-week schedule. Coverage is verified after generation and before the draft is made available for admin review. A schedule that fails coverage verification is rejected and regenerated.
Coverage statistics must be surfaced to the admin during preview:
- Total Themes in KB vs Themes scheduled
- Total Topics in KB vs Topics scheduled across all weeks
7. Estimated session duration
Each week slot carries an estimated duration in minutes (15–45 minute range). This is an AI estimate based on Topic count and complexity weights for that week. It is informational — it guides employees on time commitment but does not enforce a time limit.
Data model (logical)
These are logical entities. Implementation may map them to any storage system.
CurriculumVersion
id
version_number integer, increments on each generation
status draft | active | superseded
generated_at datetime
generation_reason string
confirmed_by user reference
confirmed_at datetime
CurriculumWeek
id
curriculum_version → CurriculumVersion
week_number 1–26
theme → Theme
topics ordered list of → Topic
estimated_duration minutes (15–45)
week_rationale string (AI-generated, one sentence)
admin_notes string (free text, admin-authored)
EmployeeCurriculumState
id
employee → User
current_cycle integer (starts at 1)
current_week integer (1–26)
start_date datetime
active_version → CurriculumVersion
AI prompt requirements
The following requirements apply to any AI model used for generation, regardless of provider.
Input the AI must receive:
- Full KB snapshot with Themes and pre-ordered Topic lists
- Per Topic: complexity weight, difficulty, relationship types
- Cycle number (1 for first cycle, 2+ for subsequent)
- For cycle 2+: employee history (types used, types not used, low-engagement topics)
Output the AI must produce:
- Exactly 26 week slots
- Each slot: theme reference, ordered topic references, estimated duration, rationale
- Structured format suitable for machine parsing (JSON or equivalent)
- No explanatory prose outside the structured output
Constraints on AI behaviour:
- Temperature should be set to deterministic or near-deterministic (0 or equivalent)
- Output must be validated before persistence — never persist unvalidated AI output
- On validation failure: retry once with a stricter prompt, then surface an error to the operator rather than persisting a partial or malformed schedule
- The AI must not invent Theme or Topic references — all references must exist in the provided KB snapshot
Admin capabilities summary
| Capability | When available |
|---|---|
| Trigger manual regeneration | Any time |
| Preview proposed schedule | After generation, before confirmation |
| View week rationale | During preview |
| Reorder weeks | During preview |
| Edit topic subset per week | During preview |
| Add admin notes per week | During preview and after confirmation |
| Confirm version | During preview |
| Reject draft | During preview |
| View coverage statistics | During preview |
| View active schedule | Any time |
| View version history | Any time |
Behaviours that must never occur
- A completed week's content changes after the employee has completed it
- A curriculum version is applied without admin confirmation
- AI output is persisted without validation against the KB
- An employee's cycle increments without week 26 being completed
- Two versions are active simultaneously
- A Theme is absent from a 26-week schedule when it exists in the published KB
- The admin is not shown a preview before a new version is applied
Acceptance criteria
- Generate a curriculum from a KB with 5 or more Themes → exactly 26 weeks produced
- All published Themes appear at least once in the schedule
- Topic order within each week respects prerequisite relationships
- Coverage statistics correctly reflect KB vs schedule coverage
- A draft version is available for preview before any employee is affected
- Admin can reorder two weeks and confirm → reordered schedule applied
- New Topics published to KB → regeneration triggered → admin sees preview → confirms → employees at week N see weeks 1 to N unchanged, weeks N+1 onward updated
- Employee completes week 26 → cycle 2 begins → sequence differs from cycle 1
- Cycle 2 schedule surfaces Topics the employee engaged with minimally
- Two employees with different start dates and current weeks both receive correct version transitions independently when a new version is applied