# Formats

Canonical formats for learnmax artifacts. `/learn`, `/quiz`, and `/test` write to these. The validator (`learnmax-validate`) enforces the structural parts.

## Mission — `<topic-slug>/MISSION.md`

One mission per topic, inside the topic dir. Captures the _reason_ the user is learning this topic. Every teaching decision traces back to it.

```md
# Mission: {Topic}

## Why
{1-3 sentences. The concrete real-world goal. What changes when they have this skill? Avoid "to understand X" — push for the outcome.}

## Success looks like
- {A specific, observable thing the user will be able to do}

## Constraints
- {Time, budget, prior commitments, learning preferences}

## Out of scope
- {Adjacent topics the user does not want to chase right now}
```

Rules: one mission per topic. Concrete over abstract ("ship a Rust CLI" beats "learn Rust"). Push back on vagueness — interview before writing. Revise when the goal moves. Keep it short; past a screen it's a plan, not a compass.

## Glossary — `<topic-slug>/GLOSSARY.md`

Canonical language for one topic. One glossary per topic, inside the topic dir. Building it is itself learning: compressing a concept into a tight definition is evidence of understanding.

```md
# {Topic} Glossary

{One or two sentence description.}

## Terms

**Term** (defined in [[<topic-slug>/lessons/NNNN-slug.md]]):
Definition in one or two sentences — what the term IS.
_Avoid_: alias1, alias2
```

Rules: every term links back to the lesson that defined it (`(defined in [[...]])`). Add a term when its lesson defines it. Be opinionated — pick the best word, list the rest as aliases to avoid. Keep definitions tight (one or two sentences, what it IS). Group under subheadings when clusters emerge. Flag ambiguities. Revise in place.

## Lesson — `<topic-slug>/lessons/NNNN-<slug>.md`

One self-contained lesson. Each teaches **one load-bearing idea** to a tangible win, tied to the Mission, with a primary-source citation. Obsidian renders it natively.

A lesson is too short if a reader could not teach the idea back from this file alone.

- File: `<topic-slug>/lessons/0001-binary-search.md` (zero-padded `NNNN`, kebab `slug`). Numbering is **local to the topic** — every topic starts at `0001`.
- Title: `# 0001 - Binary search` (number matches filename; human title follows the dash).

```md
# NNNN - {Title}

**Mission tie-in:** {One line. What the learner can now do, and which Mission goal it serves.}

## Struggle
{A deliberately broken piece of code, a wrong mental model, or a prediction
challenge. Ask the learner to predict the output / spot the bug / explain why
it fails — before any explanation. The answer is collapsed behind `<details>`
so they must generate their own answer before peeking. This primes encoding
through productive failure.}

```c
// {code snippet that demonstrates the common mistake}
```

<details>
<summary>What to notice (write your answer first)</summary>

{The key mechanism. The mistake most people make.}
</details>

## The idea
{The core claim in 2-4 sentences. What the thing IS and why it exists. No jargon before it is taught.}

## Mental model
{An analogy that fits AND where it breaks. Name the moving parts.}

## How it works
{The mechanism under the hood. Concrete, not hand-wavy.}

## Worked example 1 — {scenario}
{Step-by-step in ONE case. Real code or a real trace. Annotate the non-obvious lines.}

## Worked example 2 — {scenario}   (optional)
{A second angle: the failure mode, the edge case, or the contrast.}

## Controversy (optional)
{Pull one tension from the literature review. Two competing views, the evidence
for each, what decides. Omit for foundational concepts with no live debate.}

## Common mistakes
- {What people get wrong, and what breaks when they do.}

## Why it matters
{What breaks or what becomes possible. Tie to real bugs, costs, or leverage.}

## Connections
- Builds on [[<topic-slug>/lessons/NNNN-slug.md]].
- Sets up [[<topic-slug>/lessons/NNNN-slug.md]].

## Synthesis (lesson 2+ in a topic)
{An exercise requiring concepts from two or more lessons in this topic.
Present a concrete problem whose solution needs the current lesson AND at least
one earlier lesson. The answer is collapsed.}

<details>
<summary>Solution (write yours first)</summary>
{Walkthrough of the cross-concept solution.}
</details>

## Summary
{3-5 sentences restating the idea, the mechanism, and what goes wrong.}

## Retrieval practice
Q: {A retrieval question — "explain / predict / define", not "which of these".}

<details>
<summary>Answer (write yours first)</summary>
{The full answer. Everything needed to answer must be in this lesson above.}
</details>

## References
- {Primary source or recognised expert. Why it backs this lesson.}
```

Rules:
- **One idea per lesson.** If two ideas fight for the title, split them.
- **Self-contained.** A reader who only opens this file can learn and be quizzed on it.
- **Contain the answer.** The retrieval-practice answer must be derivable from this file alone. `/quiz` and `/test` only ask what is stated here.
- **Show, don't assert.** Every non-trivial claim gets a worked example or a concrete instance.
- **Name the common mistakes.** Mandatory — it is what the learner will actually get wrong.
- **Link forward and back.** Connections use `[[<topic-slug>/lessons/NNNN-slug.md]]` so the curriculum reads as a graph. Links may cross topic dirs.
- **Cite.** At least one primary or expert source in References.
- **Hidden answer.** Retrieval practice uses `Q:` then `<details><summary>Answer (write yours first)</summary>`. `/quiz` and `/test` parse the `Q:` line.
- **Struggle before content.** Every lesson starts with `## Struggle` — a prediction/bug-fix challenge, answer collapsed.
- **Synthesis from lesson 2 onward.** Every lesson after the first includes a `## Synthesis` exercise linking this lesson + at least one earlier lesson.

## Relearn — `relearn/`

`/test` writes two files here. Create the directory lazily.

### Per-date — `relearn/YYYY-MM-DD.md`

```md
# Review: {YYYY-MM-DD}

## Results
- {Question/Term}: {known | shaky | unknown}

## Weak Items
- {Question/Term} (from [[<topic-slug>/lessons/NNNN-slug.md]] or <topic-slug>/GLOSSARY.md)
```

Rules: record every question asked with its final score. Any item scored `shaky` or `unknown` goes in Weak Items, linked back to its source.

### Backlog — `relearn/weak-items.md`

The hand-off to `/learn`: `/learn` ingests it **first** on its next run, so weak spots become the topics for new lessons. One line per item, linked to its source, deduped by question text:

```md
- {Question/Term} (from [[<topic-slug>/lessons/NNNN-slug.md]] or <topic-slug>/GLOSSARY.md) — last: YYYY-MM-DD, streak: N
```

- `last` — date the item was last tested.
- `streak` — consecutive times scored `known`. Spacing intervals: 0 → 1 day, 1 → 3 days, 2 → 7 days. An item is **retired** (removed) when `streak` reaches 3.

`/test` rewrites this file completely on every run: due items are re-tested first, items that keep failing reset to `streak: 0`, items that stick are retired. It tracks what is *currently* weak, not everything that ever was. Lives under `relearn/` (already git-ignored); a workspace-local signal between `/test` and `/learn`, not a deliverable.