learning-platform/micro-learning-generation-spec.md

# Micro learning generation specification

## Purpose

This document defines the functional behaviour of AI-generated micro learning
content. 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

**Topic**
An atomic unit of knowledge. The source material for all micro learning
generation. A Topic has a title, a body (one or more paragraphs of content),
a difficulty level, and a set of key terms. Topics live within a knowledge
base organised into broader Themes.

**Micro learning**
A single generated learning artifact derived from one Topic. One micro
learning covers exactly one Topic in exactly one format type. Multiple micro
learnings can exist per Topic — one per type.

**Micro learning type**
The format and cognitive approach of the artifact. Ten types are defined.
Each type targets a different learning mechanism (recall, application,
comparison, reflection, and so on). See section — the ten types.

**Generation**
The act of producing micro learning content from a Topic using an AI model.
Generation always targets a specific type and produces structured output
matching that type's schema.

**Status lifecycle**
Every micro learning passes through a defined status sequence:
```
queued → generated → published
                   ↘ rejected
```

- queued: generation has been requested but not yet executed
- generated: AI has produced output, awaiting review
- published: content is available to employees
- rejected: content was reviewed and discarded; generation can be retriggered

---

## Functional requirements

### 1. Generation triggers

Generation is triggered in two situations:

**Batch trigger — Theme approval**
When an admin approves a batch of Topics (grouped under a Theme), generation
is queued for all 10 types for every Topic in that batch. This is the primary
trigger. An approved Topic that has not had all 10 types generated is
considered incomplete.

**Individual trigger — manual regeneration**
An admin may request regeneration of a specific type for a specific Topic at
any time. This replaces the existing generated artifact for that type with a
newly generated one. The replacement does not affect other types for the same
Topic.

---

### 2. One artifact per topic per type

The system maintains at most one published artifact per Topic per type at any
time. A Topic with all 10 types published has exactly 10 micro learning records.

If a type is rejected and regenerated, the previous artifact is superseded by
the new one. Rejected artifacts may be retained for audit but are never shown
to employees.

---

### 3. Generation is asynchronous

Generation must not block the user interface. Each generation request is
queued and processed in the background. The requester receives a job reference
and can poll or subscribe to status updates.

Status must be reportable at two levels:
- Per Topic: how many of the 10 types are in each status
- Per job: current processing state of the batch

---

### 4. Content quality constraints

The AI must follow these constraints for all types:

- Content must be derived from the Topic body — the AI must not introduce
  facts, claims, or examples that are not grounded in the provided Topic
- Language must match the Topic's difficulty level:
  - introductory: plain language, no assumed prior knowledge
  - intermediate: assumes familiarity with basic concepts in the domain
  - advanced: technical precision, assumes domain competence
- Length must be appropriate to the type — see per-type requirements below
- Content must be written for the employee audience, not for a general public
- Tone must be direct and factual — no motivational filler, no excessive hedging

---

### 5. Structured output

Every type produces structured output — not free prose. The structure is
defined per type in the content schemas section. The AI must produce output
that strictly conforms to the schema for the requested type.

Output validation must occur before persistence. Any output that fails
schema validation must be:
1. Retried once with a stricter prompt
2. If retry also fails: marked as failed with a reason, not persisted

---

### 6. Admin review flow

Generated content enters a review queue before becoming available to
employees. Admins may:

- Read the generated content
- Approve it → status moves to published
- Reject it → status moves to rejected, regeneration can be requested
- Edit it inline → edits are saved, status moves to published

Bulk approval is permitted: an admin may approve all generated artifacts for
a Theme in a single action. Individual review remains available for any
artifact.

---

### 7. Employee access

Employees see only published micro learnings. The set of available types for
a Topic is the set of types with published status. If a Topic has 7 of 10
types published, employees see 7 options.

Employees choose one type per Topic per session. Multiple types can be
completed in a single session. Completion of one type does not prevent
completing another type for the same Topic.

---

## The ten types

Each type is described with its learning mechanism, required content
structure, constraints, and the AI prompt intent.

---

### 1. Concept explainer

**Learning mechanism:** comprehension — understanding what something is

**Structure:**
```
paragraphs: array of 2–3 strings
example:    string
```

**Constraints:**
- Paragraphs explain the concept in plain terms, building from definition
  to context to implication
- Example is concrete and specific — not hypothetical ("for example, when
  a circle needs to..."), not generic ("this is used in many situations")
- Total length: 150–250 words across paragraphs + example
- No bullet points — flowing prose only

**Prompt intent:** explain this concept clearly to someone encountering it
for the first time, then make it concrete with a real example from the
Topic's domain

---

### 2. Scenario quiz

**Learning mechanism:** application — using knowledge to reason through a
realistic situation

**Structure:**
```
scenario: string
options:  array of 3–4 objects
  label:       string  (A, B, C, D)
  text:        string
  correct:     boolean
  explanation: string
```

**Constraints:**
- Scenario is a realistic, specific situation — not abstract ("imagine a
  team..."), not trivial ("what is the definition of...")
- Exactly one correct option
- All incorrect options must be plausible — they should represent common
  mistakes or reasonable misunderstandings, not obvious wrong answers
- Each explanation justifies why the option is correct or incorrect —
  the explanation teaches, not just confirms
- Scenario length: 60–100 words
- Option text: 15–30 words each

**Prompt intent:** create a situation where someone must apply this Topic's
knowledge to make a decision, then explain the reasoning behind each choice

---

### 3. Common misconceptions

**Learning mechanism:** correction — replacing wrong mental models with
accurate ones

**Structure:**
```
items: array of 3–5 objects
  misconception: string
  correction:    string
```

**Constraints:**
- Each misconception must be genuinely held by people learning this Topic —
  not a strawman, not an obvious error
- Correction explains why the misconception is wrong and what is true
  instead — it does not just negate the misconception
- Misconception: 1 sentence
- Correction: 2–3 sentences
- Items must be distinct — no overlapping misconceptions

**Prompt intent:** identify the most common wrong beliefs people hold about
this Topic and correct each one with an accurate explanation

---

### 4. Step-by-step how-to

**Learning mechanism:** procedural — learning a process by following steps

**Structure:**
```
steps: array of objects
  number:      integer
  instruction: string
```

**Constraints:**
- Each step is a single action — not a compound instruction ("do A and
  then B" should be two steps)
- Steps are ordered — the sequence matters and must be correct
- Step count: 4–8 steps
- Instruction length: 1–2 sentences per step
- Only applicable to Topics that describe a process or procedure — if the
  Topic does not contain a process, this type must not be generated

**Prompt intent:** decompose the process described in this Topic into a
clear ordered sequence of actions that someone can follow

---

### 5. Comparison card

**Learning mechanism:** differentiation — understanding how two related
concepts differ and when each applies

**Structure:**
```
subject_a:  string
subject_b:  string
dimensions: array of 4–6 objects
  label: string
  a:     string
  b:     string
```

**Constraints:**
- subject_a and subject_b must both be present in the Topic — do not
  compare a Topic concept against an external concept not covered in
  the KB
- Each dimension is a meaningful axis of comparison — not trivial
  ("name: A is called X, B is called Y")
- Each cell (a and b per dimension) is 1–2 sentences
- Dimensions must cover: purpose/intent, typical use, key difference,
  and at least one practical implication
- Only applicable to Topics that discuss two comparable concepts

**Prompt intent:** surface the meaningful differences between the two
concepts in this Topic across dimensions that matter for applying them

---

### 6. Reflection prompt

**Learning mechanism:** metacognition — connecting new knowledge to
existing experience and internalising it

**Structure:**
```
prompt:       string
model_answer: string
```

**Constraints:**
- Prompt is an open question that cannot be answered with a fact — it
  requires the employee to connect the Topic to their own work or experience
- Prompt must be specific to the Topic's content — not generic
  ("how does this apply to your work?")
- Model answer demonstrates what a strong reflective response looks like —
  it is not the only correct answer, but it shows the depth expected
- Prompt length: 1–2 sentences
- Model answer length: 100–150 words

**Prompt intent:** write a question that prompts the employee to connect
this Topic's content to their own professional context, then provide an
example of a thoughtful response

---

### 7. Spaced repetition flashcard set

**Learning mechanism:** recall — retrieving knowledge from memory through
repeated low-stakes testing

**Structure:**
```
cards: array of 5–10 objects
  question: string
  answer:   string
```

**Constraints:**
- Each card tests one discrete fact, term, or concept from the Topic
- Questions must be answerable with the Topic's content alone — no
  external knowledge required
- Answers are concise — 1–2 sentences maximum
- Questions must not overlap — each card tests something distinct
- Mix of question types across the set: definition questions, application
  questions, and relationship questions (how does X relate to Y)
- No trick questions

**Prompt intent:** identify the most important facts, terms, and
relationships in this Topic and create one card per item, written for
repeated low-stakes recall practice

---

### 8. Case study mini-analysis

**Learning mechanism:** analytical — applying concepts to evaluate a
realistic scenario in depth

**Structure:**
```
scenario:  string
questions: array of 2–4 strings
```

**Constraints:**
- Scenario is a fictional but realistic situation (150–200 words) that
  directly involves the concepts in the Topic
- Scenario must be ambiguous enough to require analysis — not a situation
  with an obvious single correct answer
- Questions guide analysis — they do not ask for definitions or facts,
  they ask the employee to evaluate, judge, or decide
- Questions build on each other — the set forms a coherent analytical
  arc, not isolated questions

**Prompt intent:** create a realistic situation that puts the Topic's
concepts in tension or under pressure, then ask questions that require
the employee to think critically rather than recall facts

---

### 9. Glossary anchor

**Learning mechanism:** vocabulary — precise understanding of domain terms
including how they are correctly and incorrectly applied

**Structure:**
```
term:        string
definition:  string
correct_use: string
misuse:      string
```

**Constraints:**
- Term must be a key term from the Topic — taken from the Topic's key
  terms list if available, otherwise identified from the Topic body
- Definition is precise — suitable for a reference glossary, not
  conversational
- correct_use is a concrete sentence showing the term used correctly
  in context
- misuse is a concrete sentence showing a common way the term is used
  incorrectly, followed by a brief note on why it is wrong
- Definition: 2–3 sentences
- correct_use and misuse: 1–2 sentences each

**Prompt intent:** define this term precisely, then anchor the definition
with a correct example and a counterexample that shows a common misuse

---

### 10. Myth vs. evidence

**Learning mechanism:** critical thinking — evaluating a commonly held
belief against evidence

**Structure:**
```
myth:     string
evidence: string
sources:  array of strings (may be empty if no external sources in Topic)
```

**Constraints:**
- Myth is a specific, commonly held false claim related to the Topic —
  stated as a confident assertion, not a question
- Evidence is the factual rebuttal — it explains what is actually true
  and why the myth persists
- Evidence does not simply negate the myth — it provides the accurate
  alternative and ideally explains the origin of the misconception
- Myth: 1–2 sentences, stated assertively
- Evidence: 3–5 sentences
- Sources: only include sources that are explicitly referenced in the
  Topic body — do not fabricate citations

**Prompt intent:** identify a specific false claim that people commonly
believe about this Topic's subject, state it directly, then dismantle it
with evidence and explain why the misconception exists

---

## AI prompt requirements

The following requirements apply regardless of AI model or provider.

**Input the AI must receive for every generation call:**
- Topic title
- Topic body (full text)
- Topic difficulty level (introductory / intermediate / advanced)
- Topic key terms (list)
- The specific micro learning type being generated
- The content schema for that type (what structured output is expected)

**Output the AI must produce:**
- Structured output strictly conforming to the type's schema
- No preamble, no explanation, no prose outside the schema
- All content grounded in the provided Topic body — no external facts introduced

**Constraints on AI behaviour:**
- Output must be validated against the type's schema before persistence
- On validation failure: retry once with a stricter prompt, then surface
  a failure status rather than persisting invalid output
- The AI must not add fields not present in the schema
- The AI must not omit required fields
- For types with constraints on count (flashcard_set: 5–10 cards,
  scenario_quiz: 3–4 options), the count must be within the specified range

**One generation call per type:**
Each type requires a separate AI call. Do not attempt to generate multiple
types in a single call. This ensures clean validation and clean failure
isolation — a failure in one type does not affect others.

---

## Data model (logical)

These are logical entities. Implementation may map them to any storage system.

**MicroLearning**
```
id
topic               → Topic
type                one of the ten type identifiers
content             structured data matching the type's schema
status              queued | generated | published | rejected
generation_model    identifier of the model used (for audit)
generated_at        datetime
published_at        datetime (null until published)
updated_at          datetime
```

**GenerationJob**
```
id
topic               → Topic
types_requested     list of type identifiers
status              queued | processing | done | failed
progress
  types_total       integer
  types_done        integer
  types_failed      integer
error               string (null unless failed)
created_at          datetime
completed_at        datetime (null until done or failed)
```

---

## Admin capabilities summary

| Capability | When available |
|---|---|
| Trigger batch generation for a Theme | After Theme approval |
| Trigger individual type regeneration | Any time, per Topic per type |
| View generation job status | During and after generation |
| Review generated content | After generation |
| Approve individual artifact | After generation |
| Reject individual artifact | After generation |
| Edit content inline before publishing | After generation |
| Bulk approve all artifacts in a Theme | After generation |
| View per-Topic generation coverage | Any time |

---

## Behaviours that must never occur

- Generated content is persisted without schema validation
- An artifact with status rejected is shown to employees
- A generation call produces output that introduces facts not in the Topic
- Multiple published artifacts exist for the same Topic and type simultaneously
- A how-to is generated for a Topic that contains no process or procedure
- A comparison card is generated for a Topic that contains only one concept
- Generation blocks the admin interface — it must always be asynchronous
- A failed generation is silently ignored — failure must be surfaced and
  reportable

---

## Acceptance criteria

1. Trigger batch generation for a Theme with 4 Topics → 40 artifacts queued
   (10 per Topic)
2. All 40 artifacts reach generated status without error
3. Each artifact's content validates against its type's schema
4. A generated concept_explainer contains 2–3 paragraphs and one example,
   all grounded in the Topic body
5. A generated scenario_quiz contains exactly one correct option and
   explanations for all options
6. A generated flashcard_set contains between 5 and 10 cards with no
   overlapping questions
7. An admin rejects one artifact → status is rejected → artifact is not
   visible to employees
8. Admin triggers regeneration of the rejected artifact → new artifact
   generated → previous rejected artifact superseded
9. Admin edits a generated artifact inline → edits saved → status published
10. Admin bulk-approves all artifacts for a Theme → all move to published
11. A Topic with no process content does not have a how-to artifact generated
    (generation is skipped or flagged, not forced)
12. A validation failure on AI output triggers one retry → if retry fails,
    artifact status is set to failed with reason, nothing is persisted
13. Generation job status reflects accurate progress counts throughout
    the batch process
14. Employee view of a Topic shows only published artifact types