335 lines
12 KiB
Markdown
335 lines
12 KiB
Markdown
# 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:
|
||
1. New Topics are published to the KB (new content available for scheduling)
|
||
2. 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
|
||
|
||
1. Generate a curriculum from a KB with 5 or more Themes → exactly 26 weeks produced
|
||
2. All published Themes appear at least once in the schedule
|
||
3. Topic order within each week respects prerequisite relationships
|
||
4. Coverage statistics correctly reflect KB vs schedule coverage
|
||
5. A draft version is available for preview before any employee is affected
|
||
6. Admin can reorder two weeks and confirm → reordered schedule applied
|
||
7. 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
|
||
8. Employee completes week 26 → cycle 2 begins → sequence differs from cycle 1
|
||
9. Cycle 2 schedule surfaces Topics the employee engaged with minimally
|
||
10. Two employees with different start dates and current weeks both receive
|
||
correct version transitions independently when a new version is applied
|