# 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
`docs/generation-spec.md`.

> **Current types:** the platform ships **three** micro-learning types —
> `concept_explainer`, `scenario_quiz`, and `flashcard_set`. A fourth
> (`reflection_prompt`) was specced earlier and has since been dropped.
> References to it below are retained only as historical context.

---

## 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
  └── Topic B
        ├── Concept explainer
        ├── Scenario quiz
        └── Flashcard set
```

One session covers one Theme. A Theme contains multiple Topics. Each Topic
has up to three 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 |

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 micro-learning types — learner perspective

> Three types are active: **Concept explainer**, **Scenario quiz**, and
> **Flashcard set**. The **Reflection prompt** subsection below is retained for
> historical context only — that type is not currently generated or shown.

### 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.

These map to the `micro_learnings` and `micro_learning_completions` PocketBase
collections (see `docs/data-model.md`).

**MicroLearning** (the artifact — `micro_learnings`)
```
id
topic_id            → Topic
type                concept_explainer | scenario_quiz | flashcard_set
content             structured data per type schema (JSON)
status              published (only published items are visible to employees)
```

**MicroLearningCompletion** (the event — `micro_learning_completions`)
```
id
team_member_id      → team member (employee)
micro_learning_id   → MicroLearning
topic_id            → Topic
type                type identifier at time of completion
session_week        integer — the user's absolute curriculum week when completed
created             datetime (PocketBase autodate)
```

`session_week` is the per-user absolute week counter (week 1 begins the day the
employee enrolls). The 26-week slot and cycle are derived from it; there is no
separate stored `cycle` field.

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. Completing one type for a Topic does not remove or replace the
   completion record for another type for the same Topic
6. A Topic with one completed type counts as engaged for session progress
7. An employee can access and complete micro learnings from the knowledge
   library outside of their scheduled session week
8. Each completion creates exactly one record — completing the same type
   twice creates two records, not one updated record
9. An employee in cycle 2 can complete a flashcard set for a Topic they
   completed in cycle 1 — the new completion is recorded independently
