rename micro-learning-generation-spec.md to micro-learning-spec.md

2026-05-24 23:29:18 +02:00
parent f55ec950aa
commit 8930ac03ae
2 changed files with 359 additions and 556 deletions
--- a/micro-learning-generation-spec.md
+++ b/micro-learning-generation-spec.md
@@ -1,556 +0,0 @@
 # 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
--- a/micro-learning-spec.md
+++ b/micro-learning-spec.md
@@ -0,0 +1,359 @@
 # Micro learning specification
 ## Purpose
 This document defines what micro learnings are, how employees experience
 them, and how they behave within a learning session. It covers the learner
 perspective — interaction patterns, completion rules, and the relationship
 between micro learnings, topics, and sessions.
 This document is application-agnostic. It does not describe how micro
 learnings are generated, stored, or administered. For those topics see the
 micro learning generation specification.
 ---
 ## What a micro learning is
 A micro learning is a short, focused learning interaction derived from a
 single Topic in the knowledge base. It presents the content of that Topic
 through one specific format designed to activate a particular cognitive
 process.
 A micro learning has three defining characteristics:
 **Single topic scope**
 Every micro learning covers exactly one Topic. It does not introduce content
 from other Topics, even related ones. If an employee needs to understand a
 related concept, they access that Topic's micro learnings separately.
 **Single format**
 Each micro learning uses one format type. The type determines the cognitive
 demand: comprehension, application, recall, or reflection. An employee
 choosing different types for the same Topic is not repeating content — they
 are engaging the same knowledge through different cognitive processes.
 **Short duration**
 A micro learning is designed to be completed in a single sitting of five to
 fifteen minutes. It is not a course, a module, or a chapter. It is one
 focused interaction.
 ---
 ## Relationship to topics and sessions
 ```
 Theme (one per weekly session)
  └── Topic A
  │     ├── Concept explainer   ← micro learning
  │     ├── Scenario quiz       ← micro learning
  │     ├── Flashcard set       ← micro learning
  │     └── Reflection prompt   ← micro learning
  └── Topic B
        ├── Concept explainer
        ├── Scenario quiz
        ├── Flashcard set
        └── Reflection prompt
 ```
 One session covers one Theme. A Theme contains multiple Topics. Each Topic
 has up to four micro learnings — one per type. The employee selects which
 type to engage with per Topic per session.
 ---
 ## Employee choice
 The employee is never assigned a specific micro learning type. For each
 Topic in a session, the employee sees the available types and selects one.
 This choice is made fresh each time — there is no default, no locked
 sequence, and no penalty for choosing the same type repeatedly.
 The choice is meaningful:
 - An employee who wants to understand a concept for the first time will
  likely choose the concept explainer
 - An employee who already understands the concept and wants to test
  themselves will choose the scenario quiz
 - An employee revisiting a Topic in a later cycle will choose differently
  than they did in the first cycle
 The system records which types the employee has used per Topic across their
 history. This history informs curriculum variation in subsequent cycles but
 does not restrict choice in the current session.
 ---
 ## Completion
 ### What counts as complete
 Completion is defined per micro learning — one completion record is created
 when an employee finishes one type for one Topic.
 Each type has its own completion trigger:
 | Type | Completion trigger |
 |---|---|
 | Concept explainer | Employee reaches the end of the content |
 | Scenario quiz | Employee selects an answer and views the explanation |
 | Flashcard set | Employee views all cards in the set at least once |
 | Reflection prompt | Employee submits a response (any response) |
 Completion is not quality-gated. The employee does not need to answer
 correctly or respond thoughtfully. The act of engaging with the full micro
 learning constitutes completion. Learning quality is served by the content
 design and the spaced repetition mechanic — not by enforced correctness.
 ### Multiple completions per topic
 An employee may complete more than one type for the same Topic in the same
 session or across sessions. Each type completion is recorded independently.
 Completing a second type for a Topic the employee has already completed does
 not overwrite the first. Both records exist. Both contribute to the
 employee's engagement history.
 There is no requirement to complete all four types for a Topic. The minimum
 for a Topic to count as engaged within a session is one completed type.
 ### Completion and session progress
 A session is considered complete when every Topic in the week's Theme has at
 least one completed micro learning type. The employee does not need to
 complete all types for all Topics — one type per Topic is the threshold.
 This threshold is intentionally low. The goal is consistent engagement with
 the full breadth of the curriculum, not exhaustive coverage of every format
 per session.
 ---
 ## The four types — learner perspective
 ### Concept explainer
 The employee reads a structured explanation of the Topic.
 The content moves through three stages: what the concept is, why it exists
 or matters, and what it looks like in practice. The final element is always
 a concrete example anchored in the employee's domain.
 The employee reads from start to finish. There is no interaction required
 beyond reading. Completion triggers when the employee reaches the end.
 This type is appropriate when:
 - The employee is encountering the Topic for the first time
 - The employee wants to refresh their understanding before attempting
  another type
 - The Topic is definitional or structural in nature
 ---
 ### Scenario quiz
 The employee reads a realistic workplace situation and selects the best
 response from three or four options.
 The scenario is specific to the employee's domain — it involves the kinds
 of decisions, tensions, or situations the employee might actually face. The
 options are plausible — the incorrect answers represent common mistakes or
 reasonable misreadings, not obvious errors.
 After selecting an answer, the employee sees an explanation for every option
 — not just the one they chose. The explanation for the incorrect options
 teaches as much as the explanation for the correct one.
 There is exactly one correct answer. The employee is not penalised for a
 wrong selection beyond seeing the explanation that corrects it.
 Completion triggers when the employee selects an answer and views the
 explanations. Selecting and immediately closing before reading explanations
 does not constitute completion.
 This type is appropriate when:
 - The employee wants to test whether they can apply the concept
 - The Topic involves a process, a decision, or a governance question
  where context determines the right response
 - The employee wants active engagement rather than passive reading
 ---
 ### Flashcard set
 The employee moves through a set of five to ten question-and-answer cards,
 each covering one discrete fact, term, or relationship from the Topic.
 Each card presents a question. The employee considers their answer, then
 reveals the answer on the card and evaluates whether they knew it. There is
 no automated scoring — the employee self-assesses.
 The cards cover a mix of question types: what something is (definition),
 how something works (application), and how two things relate (relationship).
 This mix ensures the set tests different aspects of the Topic rather than
 repeating the same cognitive demand.
 Completion triggers when the employee has viewed both sides of every card
 in the set at least once. The employee may move through the cards in any
 order. Skipping a card and returning to it later counts — what matters is
 that all cards are seen.
 Flashcard sets are designed for repeated use. An employee who completed a
 Topic's flashcard set in week 3 may return to it in week 15 and use it
 again as a retrieval practice exercise. Each return creates a new completion
 record.
 This type is appropriate when:
 - The Topic contains terminology, definitions, or facts the employee needs
  to retain
 - The employee is in a later cycle and wants to maintain knowledge rather
  than relearn it
 - The employee has limited time and wants a quick retrieval check
 ---
 ### Reflection prompt
 The employee reads an open question that asks them to connect the Topic's
 content to their own professional experience. They write a response in a
 free-text field, then compare their response to a model answer.
 The question cannot be answered with a fact. It requires the employee to
 think about how the concept applies to their own context — their team, their
 role, their past experience, or a situation they have encountered. There is
 no single correct answer.
 After writing their response, the employee reveals the model answer. The
 model answer is not a rubric or a correction — it is an example of a
 thoughtful response that shows the depth and specificity expected. The
 employee compares their thinking to the model and draws their own
 conclusions.
 Completion triggers when the employee submits a response. The system does
 not evaluate the content of the response. An employee who writes a single
 sentence has completed the micro learning in the same way as an employee
 who writes three paragraphs. The value is in the act of reflection, not
 in the output.
 This type is appropriate when:
 - The Topic describes a practice, a structure, or a principle the employee
  is expected to apply in their work
 - The employee wants to move beyond understanding into internalisation
 - The Topic involves holacratic roles, governance, or process — areas where
  personal application is the goal
 ---
 ## Behaviour across cycles
 In the first cycle, the employee encounters each Topic for the first time.
 Their natural tendency will be to use the concept explainer to build
 understanding before using other types.
 In subsequent cycles, the employee already has a foundation. The curriculum
 may vary the recommended type based on the employee's history — surfacing
 types they have not used — but the employee retains full choice.
 The flashcard set is the type most suited to later cycles. An employee who
 understood a Topic in cycle 1 can use the flashcard set in cycle 2 and 3
 purely for retrieval practice, maintaining knowledge without re-reading
 explanatory content.
 The reflection prompt gains depth in later cycles. An employee who has
 spent six months applying a holacratic principle will reflect more
 concretely in cycle 2 than they did in cycle 1.
 ---
 ## What a micro learning is not
 **Not a test**
 The scenario quiz includes a correct answer but its purpose is to surface
 reasoning, not to grade performance. No score is recorded. No minimum is
 required to complete a session.
 **Not a course**
 A micro learning does not have prerequisites, chapters, or progression within
 itself. It is a single interaction. Depth comes from the curriculum's
 sequencing of Topics over 26 weeks, not from within any individual micro
 learning.
 **Not a substitute for the knowledge library**
 The knowledge library contains the full Topic body — the source material.
 A micro learning is a derived interaction from that material. An employee
 who wants to read the full source goes to the library. An employee who wants
 a focused learning interaction uses a micro learning.
 **Not locked to a session**
 Employees may access micro learnings for any published Topic from the
 knowledge library at any time, regardless of where they are in the
 curriculum. Completing a micro learning outside a session still records
 a completion and contributes to the employee's history.
 ---
 ## Data model (logical)
 These are logical entities described from the learner's perspective.
 Implementation may map them to any storage system.
 **MicroLearning** (the artifact)
 ```
 id
 topic               → Topic
 type                concept_explainer | scenario_quiz |
                    flashcard_set | reflection_prompt
 content             structured data per type schema
 status              published (only published items are visible to employees)
 ```
 **MicroLearningCompletion** (the event)
 ```
 id
 employee            → Employee
 micro_learning      → MicroLearning
 topic               → Topic
 type                type identifier at time of completion
 completed_at        datetime
 session_week        integer — curriculum week when completed
 cycle               integer — which cycle
 ```
 Completions are append-only. They are never updated or deleted. Each
 represents a discrete learning event in the employee's history.
 ---
 ## Behaviours that must never occur
 - An employee sees a micro learning that has not been published
 - A completion is recorded before the employee reaches the completion
  trigger for that type (e.g. recording completion before all flashcards
  are viewed)
 - A completion record is modified or deleted after creation
 - The employee is prevented from choosing a type they have already
  completed for a Topic
 - The employee's response to a reflection prompt is evaluated, scored,
  or shown to anyone other than the employee themselves
 - A micro learning introduces content that is not present in its source Topic
 ---
 ## Acceptance criteria
 1. An employee accessing a Topic sees only published micro learning types
 2. An employee can complete a concept explainer by reading to the end —
   no further interaction required
 3. An employee who selects an incorrect answer in a scenario quiz sees
   explanations for all options, not only their chosen option
 4. An employee cannot complete a flashcard set without viewing all cards
 5. An employee who submits any text in a reflection prompt completes the
   micro learning — the content of the response is not evaluated
 6. Completing one type for a Topic does not remove or replace the
   completion record for another type for the same Topic
 7. A Topic with one completed type counts as engaged for session progress
 8. An employee can access and complete micro learnings from the knowledge
   library outside of their scheduled session week
 9. Each completion creates exactly one record — submitting a reflection
   prompt twice creates two records, not one updated record
 10. An employee in cycle 2 can complete a flashcard set for a Topic they
    completed in cycle 1 — the new completion is recorded independently