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