---
name: scaffolded-math-tutorial
category: teaching
description: Build college-algebra-floor, self-study tutorials that teach statistical formulas and derivations from the ground up — primers before use, a closure-audited glossary, self-explanation + faded worked examples, and folded-answer checkpoints, rendered as dual HTML/PDF Quarto
---

# Scaffolded Math Tutorial

**Turn a paper, proof, or formula into a self-study course a motivated reader can learn from *alone* — nothing undefined, every prerequisite taught before it is used, understanding checked at every step.**

Use this skill when working on: teaching a statistical derivation or formula step by step; converting a methods proof into a learnable tutorial; writing a "technical addendum" or self-study course; explaining estimands/test statistics/asymptotics to a reader with only college algebra + intro calculus; or auditing an existing tutorial for undefined jargon and forward references.

This skill is **conversational** — Claude Code reads the source material and writes the tutorial directly (no API key, full repo context). It is **domain-general**; project-specific notation and sources are supplied by the caller (e.g. a project's `/tutor` command).

---

## The non-negotiable standard

> A motivated reader who knows only **college algebra and introductory calculus** can learn every concept from the document alone. Nothing is left undefined, every prerequisite tool is taught before it is used, and understanding is checked at every step. *If a term would send the reader to Google or a textbook, the document has failed.*

State the assumed floor explicitly at the top ("this course assumes only …") and teach everything above it, in dependency order.

## The four pillars (how to hit the standard)

1. **Zero undefined jargon.** On a term's first use, give in order: (a) a one-line plain-language gloss, (b) a precise definition, (c) a tiny example where it helps. Maintain a running **glossary** (the reader's panic button). Ban "clearly", "obviously", "it is well known", "it follows that".
2. **Teach the prerequisites.** Before any step that uses a foundational tool, insert a short **Primer box** that teaches the tool from scratch with a minimal worked example, *then* apply it. Never use a tool before its primer.
3. **Self-explanation backbone, quizzing as supplement.** Make "explain *why* this step follows" prompts and **faded worked examples** the load-bearing pedagogy (strongest, cheapest evidence for math — see `reference/pedagogy.md`). Keep attempt-before-reveal **Checkpoints** and one **end-of-section quiz** + a **cumulative final**, but do *not* saturate every subsection with quizzes.
4. **Teaching scaffold.** Open each section with **learning objectives** ("after this you can …") and close with a "you can now …" recap. Give every abstract claim a **worked numeric instance**. Use progressive disclosure, analogies (flagged as analogies — they motivate, they do not prove), labeled diagrams, and explicit common-misconception callouts.

**Rigor guardrail:** an analogy or simplification may *never* introduce an error. If the material proves things, the tutorial must stay correct.

---

## The Terminology Closure Audit (Pillar 1, made enforceable)

"Define every term" is unverifiable without a verification pass. Three rules + a final audit catch the failures that slip through:

1. **Compound-term rule.** A glossed head noun does *not* discharge a modified phrase. Define the phrase *as used* **and** each meaning-bearing modifier. Test: if removing the modifier changes the math, the modifier needs its own gloss→def→example. (Canonical trap: "projection" is glossed but "$\mathcal I$-orthogonal projection" — and the "$\mathcal I$-norm" it rests on — are not.)
2. **Closure / no forward references.** A definition may use only already-defined terms. Define the metric before the operation built on it (the $\mathcal I$-norm primer precedes the $\mathcal I$-orthogonal projection).
3. **Mandated audit pass.** After drafting, sweep the document and enumerate every technical term *and compound phrase* in order of first appearance. For each, confirm (i) gloss→def→example at or before first use, (ii) non-circular, (iii) every symbol in it already defined. Emit a coverage report.
4. **One symbol, one meaning — flag context-dependent forms.** When a symbol legitimately takes *different forms in different contexts*, the audit must catch it and the tutorial must state **which form applies to which reference** — never let one definition silently stand in for the other. The signature defect (seen repeatedly in generated tutorials): a degrees-of-freedom $\nu$ defined once (e.g. the *scalar Rubin* $(m-1)(1+1/r)^2$) and then attached to a *different* reference that needs another form (e.g. the *Meng–Rubin/LRR* pooled-LRT df) — numerically far apart (≈62 vs ≈48.5 in a real case), so the document contradicts itself. Relatedly, never state a quantity *equals* a function of itself (e.g. ARIV **is** $r$; the deflation factor $1/(1+r)$ is a function *of* $r$, not ARIV itself).

**Audit algorithm** (run before rendering):
(a) extract terms + compound phrases in appearance order; (b) coverage check; (c) closure check; (d) topological-sort primers, reorder violations; (e) mechanical sweep — grep banned words and any symbol used before its glossary row, **and check that any symbol carrying more than one formula across the document is explicitly disambiguated per context** (rule 4); (f) output a coverage + violations report. (a)–(d) are reasoned; (e) is grep-checkable:

```bash
grep -nE '\b(clearly|obviously|trivially)\b|it is well known|it follows that|one can show' tutorial.qmd
```

A phrase that fails any check is a **bug**, not a stylistic nit. Fix before declaring the document done.

### Suite-level closure audit (cross-document)

The per-document audit above cannot catch a term the *whole set* leans on but
*no member defines* — e.g. "MAR + congenial imputation" was the stated validity
assumption in six tutorials, none of which defined **congeniality**. The fix was
an entire new tutorial.

When auditing a **set** of tutorials, also run a cross-document pass:

1. Collect every term that appears in an *assumption* context — after `Assumes:`,
   `under …`, `requires …` — across all files in the set.
2. For each collected term, check that **at least one** tutorial in the set
   actually defines it (gloss → definition → example), not merely glosses it.
3. Flag any invoked-but-nowhere-defined term as a **suite gap** = a missing tutorial.

Grep seed:

```bash
grep -rhoE '(Assumes:|\bunder\b|\brequires\b)[^.]*' docs/tutorials/*.qmd
# then diff the set of assumed terms against the set of defined terms
```

---

## Depth modes (the unit of one tutorial)

| Mode | Scope | Shape |
|---|---|---|
| `formula` | one formula/concept | floor → primer(s) → derivation → worked instance → self-explanation prompt → Checkpoint → mini-quiz → recap |
| `derivation` | one proposition/proof | the above, plus dependency-ordered steps, each justified ("which rule licenses this move and why it is legal here") |
| `course` | a whole topic | a roadmap (symbols + glossary + dependency table) and several dependency-ordered **rungs**, each a `derivation`, plus cumulative final quiz, self-diagnostic, and appendices |

Apply all four pillars *fully* regardless of mode (per the standard); depth selects *scope*, not rigor.

### Optional organizing pattern: the suite (spine + decompositions + index hub)

Depth modes scope *one* tutorial; a **suite** is the level above — multiple tutorials with their own structure:

- A **spine**: one `course`-mode document carrying the full derivation.
- N **decomposition** mini-tutorials: each a `formula`/`derivation` expanding
  *one rung* of the spine; each stays *self-contained* (re-teaches its primers)
  yet *positioned* (the index names its spine home).
- An **index hub** grouping them into an argument arc, cross-linking three ways:
  **forward** (mini-tutorial → its spine rung), **sideways** (sibling → sibling
  for shared tools), and **reading paths** (named routes through the set).

The index's three reference columns — one row per mini-tutorial (fill the `…` cells):

| tutorial | teaches | spine-home |
|---|---|---|
| … | … | … |

---

## What to include (the device catalog)

A full tutorial contains, in order:

1. **Frontmatter** — dual output: HTML (folded answers, KaTeX) + PDF (answers open, TikZ). See render conventions below.
2. **How-to-use callout** + a one-sentence "the theorem this course earns".
3. **Roadmap** (course mode): assumed-floor statement; three reference tables — **symbols-at-a-glance**, **bridge-to-literature** (local symbol ↔ standard notation ↔ where you'll meet it), **running glossary**; and a **rung-dependency table**.
4. **Per rung/section**: learning objectives → "Plain words" preamble → **Primer boxes** (for each new tool) → derivation (equations introduced in prose; **boxed result + inline assumptions**; geometric "the picture" notes) → **self-explanation prompt** + **faded worked example** (full → partial → blank) → **Checkpoint** → folded **Answer** → "you can now…" recap.
5. **End-of-section quiz** (3–5 items spanning recall/application/reasoning; misconception-targeting MC distractors) with a folded answer key + section pointers for each miss.
6. **Cumulative final quiz**; **self-diagnostic checklist** (failure-mode → section); **common misconceptions** ("No — [fact]" pattern).
7. **Appendices** (course mode): dependency graph (Mermaid for HTML / TikZ for PDF — the *same* DAG); map to manuscript sections; fully-worked closed-form derivations.

### Quarto syntax for each device

```markdown
::: {.callout-note}
## Primer — <tool>
<plain gloss>. <precise definition>. *Tiny example:* <numbers carried to a checkable result>.
:::

::: {.callout-note}
## Learning objectives
After this section you can: (1) … (2) … (3) …
:::

::: {.callout-tip}
## Checkpoint <n>
<attempt-first question>
:::

::: {.callout-note collapse="true"}      <!-- folded in HTML, open in PDF -->
## Answer
<full worked answer>
:::

::: {.callout-warning}
## Common misconceptions
- **"<myth>."** No — <fact>; <why>.
:::
```

- **Boxed result + assumptions:** `$$\boxed{\ <result>\ }$$` immediately followed by `*Assumes:* <list + scope conditions>`.
- **Reference tables:** three-column markdown tables (symbol/term | plain gloss | precise form-or-location).
- **Faded worked example:** show the computation fully once, then a near-identical one with the key step blanked for the reader, then one with only the setup.

### Render conventions (dual HTML + PDF)

```yaml
format:
  html: { toc: true, html-math-method: katex, theme: cosmo }
  pdf:
    toc: true
    include-in-header:
      text: |
        \usepackage{tikz}
        \usetikzlibrary{positioning, arrows.meta, calc}
```

- HTML keeps Answers **folded** (`collapse="true"`) for self-study discipline; PDF shows them all.
- **Diagrams:** Mermaid wrapped in `::: {.content-visible when-format="html"}`; an equivalent **TikZ** block in ```` ```{=tex} ```` for the PDF path (Mermaid silently fails in PDF). Keep both encoding the same DAG.
- **LaTeX-safe math** for PDF: write `\theta^*`, not `\theta^\*`; no raw non-ASCII inside `$…$`.
- If the project's root `_quarto.yml` scopes `render:` to one file, render the tutorial in a project-free temp dir to escape that scope.

**Render-scope trap (silent wrong output, not a no-op).** A root-level
`quarto render docs/tutorials/x.qmd` under a `project: type: manuscript` does
**not** no-op — it **mis-renders the file as a manuscript notebook embed** at
`_manuscript/docs/.../x-preview.html` (no theme, no folded answers, wrong
frontmatter), **exits 0, and creates a file.** Trusting exit-0 + file-exists
ships the wrong artifact. The temp-dir escape above *prevents* this trap; the
render-gate below *detects* it when it still fires.

**Render-gate (read the artifact, not the exit code).** Acceptance is NOT
exit-0 and NOT file-existence. After rendering:

1. Confirm the output is at the **expected path** (not under `_manuscript/…/-preview.html`).
2. `grep` the artifact for expected content (`katex`, `mermaid`, and a known
   string from the tutorial body).

```bash
out=tutorial.html   # run from the render output directory
grep -q katex "$out" && grep -q "<known tutorial heading>" "$out" \
  || { echo "RENDER GATE FAILED: wrong/empty artifact"; exit 1; }
```

Substitute `<known tutorial heading>` with a fixed string that appears in every
correct render of *this* tutorial (e.g. its H1 title) — do not grep for the
literal placeholder.

(The project's own recurring lesson — "exit 0 + file-exists lied 3×" — generalized.)

### Render portability — the standalone document inherits nothing

A standalone tutorial is rendered *outside* the host project, so it inherits
none of the host's preamble/macros/project config. Four traps follow:

1. **Project-defined LaTeX macros leak as undefined.** A formula using a host
   macro (e.g. apaquarto's `\indep`) renders inside the manuscript and **fails
   standalone**. Rule: *use only stock LaTeX+KaTeX macros, or macros defined in
   the tutorial's own frontmatter.* Prefer self-contained substitutes
   (`\perp\!\!\!\perp` for `\indep`, `\mathbb{E}` for a project `\E`). Audit:

   ```bash
   grep -ohE '\\[a-zA-Z]+' tutorial.qmd | sort -u   # dump every macro; manually subtract the stock LaTeX/KaTeX set, what remains is project-custom
   ```

2. **`\*` is *any* starred superscript.** In prose, Pandoc reads a bare `*` as
   emphasis, so authors reflexively escape it `\*` and carry that habit into math
   (`f^*`, `x^*`, `\hat\theta^*`) — but inside `$…$` Pandoc does not treat `*` as
   emphasis, so plain `*` is correct and `\*` is an undefined control sequence
   under LaTeX (reinforcing the `\theta^*` rule above). Audit (must be empty,
   outside code spans that document the rule):

   ```bash
   grep -nE '\\\*' tutorial.qmd
   ```

3. **TikZ minimal-preamble checklist.** Load `positioning, arrows.meta, calc`
   (`calc` is required for `$(a)!0.5!(b)$` midpoints). Give **edge** labels
   single-line text or `align=center` (an edge-node `\\` errors "Not allowed in
   LR mode"); keep `\\` line breaks only in vertex nodes whose style sets `align`.
4. **Relocated HTML needs `embed-resources`.** Quarto's default HTML emits a
   `<name>_files/` sidecar; any build that moves the `.html` out of its render
   dir (the project-free temp-dir pattern always does) breaks styling/math.
   Render with `embed-resources: true` (frontmatter) or `-M embed-resources:true`
   (flag) → one self-contained file.

### Notation contract

- **Define estimands before symbols.** Introduce the quantity ("the indirect effect — the thing we test") before its symbol (`$ab$`).
- Use the project's strict notation; add a **bridge-to-literature** table mapping local symbols to standard names.
- Flag any needed-but-unverified fact as `[CITE]` — never invent results, numbers, or citations.

---

## Workflow

1. **Scope & floor.** Pick the depth mode; state the assumed math floor.
2. **Gather sources.** Read the source math + the project's notation contract. List the concepts to teach.
3. **Order by dependency.** Build the term/primer dependency DAG; this fixes primer order and (course mode) the rung order.
4. **Draft** per the device catalog — pillars 1/2/4 fully; self-explanation + faded examples as the backbone; quizzes per policy.
5. **Closure audit.** Run the audit algorithm; fix coverage/closure/ordering violations + the banned-word sweep.
6. **Render-check** both HTML and PDF; fix LaTeX/PDF-safety issues.

---

## Integration with other skills

This skill works with:

> Invoke any of these via the `Skill` tool as `scholar:<name>` (e.g. `scholar:proof-architect`). The bare names below are the skill identifiers.

- **proof-architect** — for the rigorous proof skeleton a `derivation`/`course` tutorial teaches (this skill is the pedagogical presentation layer over it).
- **mathematical-foundations** — source of the core concepts and theorems to scaffold (sufficiency, Fisher information, asymptotics).
- **asymptotic-theory** / **identification-theory** — for limiting-distribution and causal-identification material taught pedagogically.
- **methods-paper-writer** — when a tutorial's result is promoted into a manuscript (shared VanderWeele/standard notation).
- **`/teaching:lecture`** (command) — lecture notes are the broader-coverage cousin; this skill is the deep single-derivation treatment.

---

**Version**: 1.0
**Created**: 2026-06-12
**Domain**: Statistical teaching, mathematical pedagogy, self-study course design
**Prerequisite skills**: proof-architect, mathematical-foundations
**Reference**: `reference/pedagogy.md` (learning-science basis + per-formula checklist + citations)