--- name: teachback description: Build or deepen a single-file interactive HTML explainer that teaches back difficult material already established in the conversation (or a named subject/source). Use when someone wants a durable, self-contained lesson with rendered mathematics, an exploratory multiple-choice assessment, and a terminology loop that lets the reader push unfamiliar terms back for deeper coverage. --- # teachback — teach the material back as a self-contained interactive page > **Self-Evolving Skill**: this file improves through use. If an instruction here is wrong, a gate rejected a page it should have accepted, or you needed a workaround — fix this file immediately, don't defer. Only for real, reproducible issues. And when you add a check to a gate, add the mutation that proves it can fail: an unexercised check is not yet a check. Produces **one HTML file** that explains hard material to an intelligent reader with no assumed specialist background. The page runs from `file://` with no server, no tracking and no framework. The defining behaviour: **teachback reads what is already in the working context.** Do not ask the reader to restate material the conversation already contains. Infer the subject, scope, prerequisites, title, filename and technical depth. > **This copy is canonical.** teachback was built in `example-org/research-repo` and merged there as [#527](https://github.com/example-org/research-repo/pull/527) after eleven review rounds; it was promoted to [terrylica/cc-skills](https://github.com/terrylica/cc-skills) on 2026-08-20 to make it available in every project rather than one repository. **Edit it here.** The research-repo path `.claude/skills/teachback/` is being reduced to a redirect stub carrying no gate scripts; until that lands, two full copies exist and only this one is authoritative. If you find yourself editing the research-repo copy, stop and edit this one. --- ## Options Every option is optional. `/teachback` with no arguments is the common case. | Option | Effect | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | _(none)_ | Explain the most recent coherent discussion in the working context. | | `` | Explain a named subject instead, e.g. `/teachback the spanning admission result`. | | `--source ` | Explain designated material rather than the conversation: a file, `#123`, a doc path, a URL. | | `--out ` | Write the page here. **Default: `~/Documents/explainers/.html`, outside the repository** — generated pages are artefacts, not source. Pass an in-repo path only when the page is meant to be committed. | | `--update ` | Revise an existing page in place instead of creating one. Implied by `--terms` and `--revise`. | | `--terms "a, b, c"` | **The terminology loop.** Add or substantially deepen coverage of these terms in an existing page. This is what the page's own footer form emits. | | `--revise ""` | Any other change to an existing page, in plain language. | | `--depth intro\|standard\|deep` | How much advanced qualification to carry. Default `standard`. `deep` keeps every limitation, objection and open question. | | `--questions ` | Assessment size. Default 3–8, chosen to cover the objectives. | | `--open` / `--no-open` | Launch the default browser on completion. Default `--open`. | | `--dark` / `--light` | Force a colour scheme. Default: follow the operating system. | **Composition:** `--terms`, `--revise` and `--update` operate on an existing page and always append a revision-ledger entry. Everything else builds a new page. --- ## What the page must contain Include a section only when it materially improves understanding. Do not pad to fill a structure. 1. Orientation and explicit learning objectives 2. A concise 101-level account 3. Prerequisites and terminology 4. Canonical definitions 5. Components, variables, actors, stages or layers 6. The literal mechanism or logical sequence 7. Conditions, boundaries, exclusions, common confusions 8. A real example, a non-example, and a near-miss 9. A justified worked application 10. Advanced qualifications, limitations, exceptions, open questions 11. The diagnostic assessment 12. The terminology request form and the revision ledger ### Provenance marking is mandatory Distinguish three kinds of statement, visibly, with the `.prov` spans: - `SOURCE-ESTABLISHED` — measured or stated in the underlying material - `INFERENCE` — explanatory reasoning added by the explainer - `OPEN` — unresolved, contradictory, or missing evidence **Mark contradictions and uncertainty; never invent a resolution.** Where a later correction supersedes an earlier statement in the source material, the correction wins and the supersession is stated. ### Pedagogy constraints Reduce prerequisite burden and linguistic complexity **without** reducing technical precision. Preserve accepted terminology, definitions, mechanisms, causal relationships, boundary conditions and qualifications. **Do not use analogies, metaphors, fictional comparisons, or approximate substitutions that alter the concept.** Explain the thing itself. --- ## Mathematics Render with **MathJax 3**, from a version-pinned CDN URL carrying a **subresource-integrity hash**: ```html ``` **Never point the primary source at a local absolute path.** An earlier version of this skill prescribed `file:///Users//node_modules/mathjax/...` with a JavaScript `error` fallback to the CDN. Measured, that fallback does fire and the page does render — but the pattern is wrong twice over: the path cannot travel with the artifact, and served over http(s) a browser refuses `file://` subresources outright, logging `Not allowed to load local resource` and leaving the generating machine's home directory in the DOM for anyone who receives the file. `integrity` pins the bytes, not merely the URL: a swapped or compromised CDN object fails to execute rather than running silently. Recompute it if the pinned version changes — `curl -sSL | openssl dgst -sha384 -binary | openssl base64 -A`. If a page must render with no network at all, pre-render the mathematics to **SVG** at generation time rather than adding a local script source; SVG output inlines glyph paths, so it needs no font requests. Do not add a `file:` source to a page that will be shared. - Preserve every material equation, variable, operator, constraint, domain, assumption and subscript. - Give consequential equations **stable numeric identifiers** and keep them stable across revisions. - Put the **raw LaTeX in a `
` panel** beneath each numbered equation so it is recoverable. - Define symbols, units, assumptions and validity conditions near first use. - Explain what each equation asserts and how its terms relate; show consequential intermediate steps. - Distinguish source equations from added derivations. - If an expression looks wrong or ambiguous, **preserve it and add a marked note** — never silently correct or simplify it away. - Never render mathematics as images, canvas, or Unicode approximations. Rendering the equation correctly is the floor, not the goal. Every equation must additionally satisfy **Notation accessibility** below. --- ## Notation accessibility (release-blocking) The reader is assumed to be **symbolically illiterate but not unintelligent**: fluent in the subject matter, unpractised at decoding notation. An equation printed bare forces them to hold a symbol in memory, hunt for its definition in surrounding prose, carry the meaning back, and repeat — the _split-attention effect_, and it is the single largest avoidable cost on a page like this. Every numbered equation carries **four** things. Fewer is a defect, not a style choice. ### 1. Systematic colour encoding Colour symbols by the **kind of thing they are**, with one fixed vocabulary reused across the whole page. The same colour must mean the same role in every equation; a symbol must never change colour. | Role | Meaning | Typical symbols | | ---------- | ------------------------------------------- | --------------- | | `sym-out` | the quantity the equation exists to define | Δ, α, IR | | `sym-pos` | positions, weights, loadings — what is held | w, w⋆, β | | `sym-ret` | returns; what an instrument or book earned | r, g, y, e | | `sym-time` | time indices, counts, block labels | t, i, T | | `sym-cost` | costs, turnover, penalties | c, κ, λ | | `sym-disp` | dispersion, covariance, risk aversion | σ, Σ, γ | Adapt the _roles_ to the subject; keep the _discipline_. Six is near the ceiling — beyond that the key itself becomes the thing to memorise. Implementation is fixed, because the obvious version silently fails: ```js // Listing the package is NOT enough. tex-mml-chtml does not bundle the html extension, so without // this loader entry \class renders as literal red "\class" text in the output. loader: { load: ['[tex]/html'] }, tex: { packages: { '[+]': ['html'] } } ``` Then `$\class{sym-out}{\Delta} = \class{sym-pos}{w}\,\class{sym-ret}{r}$`, with colour defined **once** per role as a CSS custom property. Use a colourblind-safe palette (Okabe–Ito) and give every role a distinct dark-mode value; a hue that reads well on white can vanish on near-black. Two properties make the code trustworthy, and both are checked: - **One role per symbol, everywhere.** A symbol that is `sym-out` in one equation and `sym-disp` in another teaches the reader that the colour is arbitrary. - **The code extends into prose.** A symbol mentioned in a paragraph carries the colour it was given in the equation that defined it. An encoding applied only inside the equation boxes reads as decoration. Colour _role-bearing symbols_ only — a bare statistic such as `p = 0.027` has no role, and colouring it dilutes the vocabulary. **Verify by inspecting the emitted DOM, never by assuming.** Count `mjx-container .sym-*` occurrences and read back `getComputedStyle().color` in both schemes. A silent `\class` failure looks like ordinary red text and is easy to scroll past. ### 2. Colour is redundant, never load-bearing Every coloured symbol also carries a **chip** beneath its equation: the symbol, what it means in ordinary words, and its shape or value. Nothing on the page may require distinguishing two hues. Chips sit **directly under the equation they annotate** — spatial contiguity. A legend elsewhere on the page reintroduces exactly the hunting the colours were meant to remove. **Every chip declares which symbols it explains, in `data-symbol`, verbatim as they appear inside `\class{…}{…}`, separated by `|`:** ```html t, t−1the bar being scored, and the bar before itthe weight is fixed at t−1, so it cannot use anything observed at t ``` Declared rather than inferred, because the chip renders `μ_p` as glyphs while the source says `\mu_{p}`; matching them would be a normalisation guess, and a guess that fails reads as coverage. The gate requires every `(role, symbol)` pair an equation colours to be declared by one of its chips. Comparing role **sets** is not enough — an equation colouring both `g` and `n` as `sym-out` with one chip has identical sets on each side, which is how `t`, `t−1`, `g` and `R` stayed coloured and unnamed in the reference page through several rounds of review. ### 3. A notation key before the first equation (pre-training) Introduce the role vocabulary and the typographic conventions — bold means a collection, a subscript is a label and not a multiplication, a star means "chosen to be best" — **before** the first equation, never inline with it. Learning six categories once is cheaper than decoding forty symbols later. The key must survive the expert switch below: it is the only place the encoding is decoded, so hiding it strands the reader with an undocumented code. ### 4. Equation as a sentence, then as numbers Each equation gets: - a **`Reads as`** block — the equation restated as one plain-language sentence, subject and verb, no symbols. Not a gloss of the notation; a statement of what it asserts. - a **`With numbers`** block — the equation instantiated with the actual figures from the material, including what the result was and why. Where a real figure is unavailable, say so; never invent one. Both blocks contain mathematics, and **mathematics cannot line-break**. Give `.eq`, `.reads` and `.numbers` `overflow-x:auto` so a long expression scrolls inside its own block. Omitting this was measured at 120px of _page-level_ horizontal scroll on a 390px viewport, caused by one inline arithmetic line — a local formatting choice turning into a whole-document defect. Use `\underbrace{...}_{\text{...}}` to name multi-term groups **inside** the equation. This is _signalling_: it partitions a wall of symbols into two or three named chunks that can be read independently, and it is the one annotation the reader cannot fail to associate with the right terms. ### 5. Expertise reversal — all of it must be switchable The same annotation that measurably helps a first reading measurably **hinders** a reader who has internalised the notation, because reconciling redundant explanation is itself work. Provide one page-level control that hides the readings, chips and worked numbers; keep the colour encoding and the notation key, since neither costs vertical space. Persist the choice in `localStorage` inside a `try`/`catch` — private-browsing mode must degrade to "not remembered", not to a thrown error. ### 6. Do not claim accessibility features you have not verified Recorded negative, so it is not re-attempted blind: the **MathJax a11y explorer is not usable in a portable single file.** Measured on 2026-08-18 — 1. `loader.load: ['[a11y]/explorer']` resolves the unregistered `[a11y]` prefix against the _document_, 404s, and **aborts MathJax startup**: container count 8 → 0. An optional extra took every equation. 2. Loading it after startup with the path repaired throws `EnrichedMathItemMixin`, because the bundle registers no dependency metadata for `[a11y]` either. 3. Loading the whole chain in order (`sre`, `semantic-enrich`, `complexity`, `explorer`) succeeds and sets `explorer = true`, but **no `aria-label` and no `data-semantic-speech` is ever attached**, even after a forced `rerender()`. The module is present and inert. Hard-coding the `a11y` path at config time works locally, but the artifact is meant to travel and a stale absolute path then takes the equations down with it. The `Reads as` sentence is the substitute, and it is purpose-written prose rather than machine-generated speech. If a future revision does enable speech, gate the on-page claim on the capability actually being present, not on the module loading. --- ## Layout - Page shell occupies **92–100%** of desktop width; no globally narrow container. - **Body text fills the content column.** Operator decision 2026-08-18: a 65–80ch cap beside a wide shell leaves a large void to the right of every paragraph, which reads as hard-wrapped text. Prose, cards, tables, equations and the assessment all use the same width. Do not reintroduce a prose cap or a marginalia rail without being asked. - **Contents is a collapsed sticky `
` disclosure, not a sidebar rail.** Operator decision 2026-08-18: a permanent rail spends horizontal space on navigation that is consulted occasionally. Closed it costs one ~40px bar; open it expands to a multi-column list. Native `
` keeps it keyboard-accessible and working with JavaScript disabled. - **Do not make `.shell` a grid.** If it ever becomes one, every direct child (`header`, `nav`, `main`, `footer`) needs an explicit `grid-column`. A child without one auto-flows into the next free cell — which is column 1 — and that is how the revision ledger once rendered inside the narrow contents column. **These are RENDERED invariants, and only `verify_rendered.py` may assert them.** Do not add a layout check to the static gate. Whitespace and declaration order are insignificant in CSS, so matching source text is unsound in principle, and it was unsound in practice: the pattern `.shell{display:grid` matched, while the exactly equivalent `.shell { display: grid; }` bypassed the grid-child check entirely — the check silently enforced nothing on any page whose CSS happened to be formatted (example-org/research-repo#527 review, finding 4). The rendered gate reads these back from `getComputedStyle` and from measured geometry, where formatting cannot change the answer. - Keyboard navigation, visible focus, sufficient contrast, dark mode, print, and full intelligibility with JavaScript disabled (JS is required only for assessment validation and the terminology form). - Keep all explanatory content in the DOM. No decorative clutter, gratuitous animation, oversized hero, marketing language, or dashboard elements. --- ## Assessment — exploratory, not an examination 3–8 questions covering the major objectives, including definition/boundary recognition, mechanism or reasoning, and transfer to a new closely related case. One best answer, three purposeful distractors. **Every distractor encodes a different plausible misconception arising from the material.** No filler, trivia, deceptive wording, test-taking tricks, "all of the above" or "none of the above". **The reader is never locked out. This is the point.** - Selecting the correct answer marks it correct — and **every other option stays selectable**. - After the answer is found, clicking a distractor shows what that option assumes and why it is wrong, presented as exploration rather than failure. - Before the answer is found, an incorrect selection names the misconception and gives a targeted hint **without revealing which option is correct**, and another attempt is permitted. - Per-question reset, reset-all, and a live summary of objectives demonstrated versus needing review. - Track and report **misconceptions explored**, not just correctness. A reader who has read every distractor's explanation has learned more than one who guessed right first time. - Never transmit, store or track responses. No `localStorage`, no `fetch`, no cookies. ### Emit the assessment as JSON, not as a JavaScript literal The questions live in a **`