rsc-universal 0.1.1

package/skills/course-builder/references/grounding-and-scoping.md

@@ -0,0 +1,69 @@
+# Grounding & scoping
+
+Backward design starts from a destination. If you don't know WHO is travelling, WHAT they must
+be able to DO at the end, and the FORMAT/constraints of the trip, every outcome you write is a
+guess. This is the hard gate — incomplete grounding means STOP and ask, do not design on assumption.
+
+## The three things you must know
+
+1. **WHO — the learner and current level.** Not a demographic; a *capability baseline*. What can
+   they already do today? Absolute beginner who has never opened a terminal? Practitioner who ships
+   daily but never wrote a test? The baseline sets the floor of your first outcome.
+2. **WHAT transformation.** State it as a DO, not a topic. "They can deploy a containerized service
+   to production and roll it back" — not "Docker". The gap between the baseline and this is the course.
+3. **FORMAT + constraints.** Duration (90 min / 1 day / 6 weeks / 12 weeks), modality (live cohort
+   vs self-paced vs hybrid), group size, prerequisites you can assume, and stakes (does completion
+   certify anything?). These bound how many outcomes are honest.
+
+## The one-batch interview
+
+Ask all of it at once. Dribbling one question per message wastes the learner's patience and yours.
+
+```text
+Before I design anything, I need three things:
+
+1. WHO is this for, and what can they already DO today (their starting point)?
+2. By the end, what must they be able to DO that they can't do now? (a verb, not a topic)
+3. FORMAT: how long, live cohort or self-paced, group size, any prerequisites,
+   and does finishing certify anything?
+
+If you have a teaching profile in 02-DOCS/wiki/teaching/, point me at it and I'll reuse it.
+```
+
+If any answer is a topic ("they should know React"), push back once: *"What should they be able to
+DO with React that they can't now?"* Topics don't scope; verbs do.
+
+## The shared teaching profile (02-DOCS/wiki/teaching/)
+
+This is the **same persistence convention** `course-storytelling` uses. If the workspace follows the
+project harness, look for `02-DOCS/wiki/teaching/` first:
+
+- `02-DOCS/wiki/teaching/learner-profile.md` — WHO + baseline (reusable across both skills).
+- `02-DOCS/wiki/teaching/<course>-outcomes.md` — the outcomes you write here.
+- `02-DOCS/wiki/teaching/<course>-matrix.md` — the alignment matrix you emit.
+
+Reuse the learner profile if it exists rather than re-interviewing. When you write outcomes and the
+matrix, persist them there so `course-storytelling` can pick up the same grounding for the hand-off.
+Note in the file that the profile is shared, so neither skill clobbers the other's section.
+
+## Right-sizing scope by format
+
+The single most common failure is too many outcomes for the time. Honest ceilings:
+
+```text
+Format                     Outcomes   Bloom ceiling     Assessment shape
+Workshop (<= half day)     1-2        Apply             one hands-on artifact, no exam
+Full-day workshop          2-3        Apply / Analyze   one build + exit checklist
+Multi-week cohort          4-6        up to Evaluate     staged formative + capstone
+Bootcamp (8-12+ weeks)     5-8        up to Create       weekly formative + graded capstone
+Onboarding track           3-5        Apply             on-the-job checklists + sign-off
+Self-paced course          3-6        up to Create       auto-graded quizzes + a final build
+```
+
+Rules of thumb:
+
+- If you can't assess an outcome in the available time, it isn't an outcome for this course — it's
+  the next course. Cut it or split the course.
+- Self-paced means every formative check must grade itself (auto-graded quiz, a test suite that
+  runs). There is no instructor in the loop to give feedback.
+- A cohort buys you cheap, high-value peer assessment and synchronous checkpoints — use them.

package/skills/course-builder/references/outcomes-and-blooms.md

@@ -0,0 +1,82 @@
+# Outcomes & Bloom's revised taxonomy
+
+An outcome is a promise about what the learner can DO. Two things make it defensible: it sits on a
+**measurable verb** from Bloom's revised taxonomy, and it is **ABCD-complete** so it's actually
+assessable. This file is the verb reference, the banlist, and worked examples.
+
+## Bloom's revised taxonomy (Anderson & Krathwohl, 2001)
+
+The 2001 revision turned Bloom's original nouns into **verbs** and reordered the top two levels.
+Six ascending levels — pick the verb at the level the learner must operate at. Recall is not build.
+
+```text
+Level 1  Remember     recall, list, define, name, label, identify, state, recognize, repeat
+Level 2  Understand*  explain, summarize, classify, compare, describe, paraphrase, interpret
+Level 3  Apply        apply, use, implement, execute, run, solve, demonstrate, compute
+Level 4  Analyze      analyze, differentiate, debug, diagram, distinguish, examine, deconstruct
+Level 5  Evaluate     evaluate, critique, justify, prioritize, defend, review, assess, recommend
+Level 6  Create       design, build, compose, construct, develop, ship, formulate, generate
+```
+
+\* "Understand" is a LEVEL NAME, not an outcome verb. Write the *verb* at that level ("explain",
+"compare") — never the bare word "understand" in an outcome. See the banlist below.
+
+## The verb banlist
+
+These name a private mental state no one can observe, so they can't be assessed. Replace every one.
+
+```text
+Banned          Why                              Use instead (observable)
+understand      can't see "understanding"        explain, apply, predict, classify
+know            can't see "knowing"              list, define, recall, use
+learn (about)   describes activity, not result   produce, demonstrate, solve
+appreciate      a feeling, not a behavior        justify, critique, prioritize
+be aware of     awareness is invisible           identify, flag, distinguish
+be familiar     familiarity is unmeasurable      describe, locate, recognize
+```
+
+A quick test: can two independent graders watch the learner and agree on whether they did it? If
+not, the verb is too vague — go down to a concrete action.
+
+## The ABCD template
+
+A bare verb is not yet an outcome. Add the conditions and the success criterion.
+
+```text
+[A] Audience    the learner / the participant
+[B] Behavior    <Bloom verb> + <object>
+[C] Condition   given <inputs / tools / situation>
+[D] Degree      <what counts as success: count, accuracy, time, rubric>
+```
+
+Read as one sentence: *"Given <C>, the learner will <B> to <D>."*
+
+## Worked examples
+
+```markdown
+Bad:  Students will understand functions in Python.
+Why:  banlist verb, no condition, no degree — unassessable.
+Good: Given a problem statement, the learner writes a Python function with correct
+      parameters and return value that passes 3 of 3 provided unit tests.
+      [A] learner [B] writes a function [C] given a problem statement
+      [D] passes 3/3 unit tests
+
+Bad:  Learners will know how to handle errors.
+Good: Given an endpoint that can fail 3 ways, the learner adds error handling that
+      returns the correct status code (400/404/500) for each, verified by a test run.
+
+Bad:  Participants will appreciate clean architecture.
+Good: Given a 200-line module, the learner critiques its layering against 4 named
+      criteria and proposes one concrete refactor with justification.
+```
+
+## Course-level vs module-level outcomes
+
+- **Course-level outcomes** (3–8) are the contract: what the learner can DO when the whole course
+  ends. They tend to sit at Apply→Create and are proven by the *summative* assessment.
+- **Module-level outcomes** are the steps that build toward a course outcome. They can sit lower
+  (Remember/Understand/Apply) and are proven by *formative* checks. Each module-level outcome should
+  ladder up to at least one course-level outcome — if it doesn't, the module is an orphan.
+
+Keep the course-level list short and the module-level list a build sequence beneath it. The matrix
+(see assessment-design.md and SKILL.md) ties module work back to course outcomes so nothing floats.

package/skills/course-builder/scripts/verify.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+#
+# verify.sh — STRUCTURE/ALIGNMENT QA gate for the `course-builder` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free heuristics over your curriculum/syllabus source files. It
+#   checks the SKELETON is defensible — not whether the teaching lands (that is
+#   course-storytelling's job). Per scanned file it checks:
+#     1. Banlist verbs   — outcome-ish lines using "understand / know / learn about /
+#        appreciate / be aware / be familiar" (a vanity verb you cannot assess).
+#     2. Alignment matrix — a section mapping outcomes to modules/assessment.
+#     3. Proven outcomes  — every declared outcome id (O1, LO2, Outcome 3...) is
+#        referenced somewhere in an assessment context (flag unproven outcomes).
+#     4. Formative + summative — BOTH assessment kinds are present (flag if missing).
+#     5. Modules present  — module sections exist and reference outcomes (orphans).
+#
+#   Every finding is a WARNING by default (course design is judgement, not pass/fail).
+#   Use --strict to turn any warning into a failure (exit 1) so CI can gate on it.
+#   A missing tool is reported yellow and SKIPPED — never a failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                  # scan ./ for curriculum sources (*.md, *.mdx, *.txt)
+#   ./verify.sh --path course    # scan a subdirectory
+#   ./verify.sh --strict         # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict
+#   1  a real failure, or --strict with any warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, arrays are
+# initialised and only expanded when non-empty under `set -u`.
+
+set -euo pipefail
+
+# --- portability: runs on stock macOS bash 3.2 ------------------------------
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..43), stripping the leading "# "
+  sed -n '2,43p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# count_lines <file>: number of lines in a file; 0 if missing/empty.
+count_lines() {
+  if [ -s "$1" ]; then
+    wc -l < "$1" 2>/dev/null | tr -dc '0-9'
+  else
+    printf '0'
+  fi
+}
+
+# find curriculum source files (markdown / text). Prints one path per line.
+# Excludes the conventional 02-DOCS wiki/raw so we lint the CURRICULUM, not the profile.
+list_curricula() {
+  find "$SCAN_PATH" \
+    \( -name '*.md' -o -name '*.mdx' -o -name '*.txt' \) \
+    -type f \
+    ! -path '*/node_modules/*' \
+    ! -path '*/.git/*' \
+    ! -path '*/02-DOCS/*' \
+    2>/dev/null || true
+}
+
+# file_has <file> <pattern>: 0 if the (case-insensitive) ERE pattern appears in the file.
+file_has() { grep -iqE "$2" "$1" 2>/dev/null; }
+
+# --- ensure we have a searcher ----------------------------------------------
+if ! have grep; then
+  skip "grep not found — cannot scan curriculum sources; install grep"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# --- gather curriculum files ------------------------------------------------
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/verify-cb.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+DOCS="$TMPDIR_V/docs"
+list_curricula > "$DOCS" 2>/dev/null || true
+n_docs="$(count_lines "$DOCS")"
+
+if [ "$n_docs" -eq 0 ]; then
+  skip "no curriculum sources (*.md, *.mdx, *.txt) found under $SCAN_PATH"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Scanning %s curriculum file(s) under: %s\n\n' "$n_docs" "$SCAN_PATH"
+
+# --- heuristic markers (case-insensitive ERE) -------------------------------
+# A "curriculum-ish" file is one that talks about outcomes/objectives at all.
+# Files with no outcome language are skipped silently from the alignment checks.
+OUTCOME_LANG_RE='outcome|objective|resultado|objetiu|objectiu|learning goal'
+BANLIST_RE='\b(understand|understands|understanding|knows?|know about|learn about|learns about|appreciate|appreciates|be aware|are aware|be familiar|familiar with)\b'
+MATRIX_RE='alignment matrix|outcome.*(module|assessment)|module.*outcome|matrix'
+FORMATIVE_RE='\bformativ|quiz|checklist|exit ticket|draft|peer review|self.?check|practice'
+SUMMATIVE_RE='\bsummativ|capstone|final (project|exam)|portfolio|certif|graded (build|project)'
+MODULE_RE='^#{1,6}.*\bmodule\b|^#{1,6}.*\bunit\b|^#{1,6}.*\bweek\b|\bmódulo\b|\bmòdul\b'
+# An outcome ID like O1 / LO2 / Outcome 3 / Objetivo 1 (at most-ish line starts).
+OUTCOME_ID_RE='\b(O|LO|OBJ)[- ]?[0-9]+\b|\boutcome[- ]?[0-9]+\b|\bobjetivo[- ]?[0-9]+\b|\bobjectiu[- ]?[0-9]+\b'
+
+# per-file result buckets
+BANHITS="$TMPDIR_V/banhits";       : > "$BANHITS"
+NO_MATRIX="$TMPDIR_V/no_matrix";   : > "$NO_MATRIX"
+NO_FORM="$TMPDIR_V/no_form";       : > "$NO_FORM"
+NO_SUMM="$TMPDIR_V/no_summ";       : > "$NO_SUMM"
+NO_MODULE="$TMPDIR_V/no_module";   : > "$NO_MODULE"
+UNPROVEN="$TMPDIR_V/unproven";     : > "$UNPROVEN"
+n_relevant=0
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  file_has "$f" "$OUTCOME_LANG_RE" || continue   # not a curriculum doc; skip quietly
+  n_relevant=$((n_relevant + 1))
+
+  # 1. banlist verbs on lines that look like outcomes/objectives.
+  # An outcome line either carries outcome/objective language or an outcome ID
+  # (O1/LO2/Outcome 3/Objetivo 1...). Flag the file if any such line uses a banlist verb.
+  if grep -inE "$OUTCOME_LANG_RE|$OUTCOME_ID_RE" "$f" 2>/dev/null \
+       | grep -iqE "$BANLIST_RE"; then
+    printf '%s\n' "$f" >> "$BANHITS"
+  fi
+
+  # 2. alignment matrix / mapping present
+  file_has "$f" "$MATRIX_RE" || printf '%s\n' "$f" >> "$NO_MATRIX"
+
+  # 4. formative AND summative markers
+  file_has "$f" "$FORMATIVE_RE" || printf '%s\n' "$f" >> "$NO_FORM"
+  file_has "$f" "$SUMMATIVE_RE" || printf '%s\n' "$f" >> "$NO_SUMM"
+
+  # 5. module sections exist
+  file_has "$f" "$MODULE_RE" || printf '%s\n' "$f" >> "$NO_MODULE"
+
+  # 3. proven outcomes: each outcome ID must also appear near assessment language.
+  # Heuristic: collect distinct outcome IDs; for each, check it co-occurs in an
+  # assessment-ish line (formative/summative/assess). If a file has IDs but none in
+  # an assessment context, flag it as possibly-unproven.
+  ids="$(grep -ioE "$OUTCOME_ID_RE" "$f" 2>/dev/null | tr '[:lower:]' '[:upper:]' \
+         | tr -d ' -' | sort -u)"
+  if [ -n "$ids" ]; then
+    proven_any=0
+    for id in $ids; do
+      # normalise file IDs the same way, then look for the id on an assessment line
+      if grep -iE "$FORMATIVE_RE|$SUMMATIVE_RE|\bassess" "$f" 2>/dev/null \
+           | tr '[:lower:]' '[:upper:]' | tr -d ' -' | grep -qF "$id"; then
+        proven_any=1
+      fi
+    done
+    [ "$proven_any" -eq 0 ] && printf '%s\n' "$f" >> "$UNPROVEN"
+  fi
+done < "$DOCS" || true   # read returns 1 at EOF; harmless under set -e
+
+if [ "$n_relevant" -eq 0 ]; then
+  skip "no files contain outcome/objective language — nothing to check for alignment"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Found %s file(s) with outcome/objective language.\n\n' "$n_relevant"
+
+report_files() {
+  label="$1"; listfile="$2"
+  n="$(count_lines "$listfile")"
+  if [ "$n" -gt 0 ]; then
+    warn "$label ($n file(s)):"
+    head -n 8 "$listfile" | sed 's/^/        /'
+    if [ "$n" -gt 1 ]; then warn_count=$((warn_count + n - 1)); fi   # warn() already counted 1
+  else
+    ok "no $label"
+  fi
+}
+
+# --- report ------------------------------------------------------------------
+report_files "outcomes using a vanity/banlist verb (use a measurable Bloom verb)" "$BANHITS"
+report_files "curricula with no alignment matrix (emit outcome x module x assessment)" "$NO_MATRIX"
+report_files "curricula missing formative assessment (add during-learning checks)" "$NO_FORM"
+report_files "curricula missing summative assessment (add an end-of-course artifact)" "$NO_SUMM"
+report_files "curricula with no module/unit/week sections (sequence the build)" "$NO_MODULE"
+report_files "outcomes not referenced in any assessment context (unproven outcomes)" "$UNPROVEN"
+
+# --- markdownlint (optional) -------------------------------------------------
+if have markdownlint; then
+  ml_out="$TMPDIR_V/mdlint"
+  # shellcheck disable=SC2046  # word-splitting the file list is intended here
+  markdownlint $(cat "$DOCS") > "$ml_out" 2>&1 || true
+  if [ -s "$ml_out" ]; then
+    warn "markdownlint findings in curriculum sources:"
+    head -n 10 "$ml_out" | sed 's/^/        /'
+  else
+    ok "markdownlint clean on curriculum sources"
+  fi
+else
+  skip "markdownlint not found — skipping markdown lint (npm i -g markdownlint-cli)"
+fi
+
+# --- summary -----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+cat <<'EOF'
+
+Note: every finding above is a heuristic WARNING — course design is judgement, not pass/fail.
+This gate checks STRUCTURE and ALIGNMENT (measurable verbs, the matrix, proven outcomes,
+formative + summative), NOT whether the teaching lands — that is course-storytelling's job.
+Review each finding: fix the skeleton or justify it. Re-run with --strict to gate CI.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/course-storytelling/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: course-storytelling
+description: "Use when you have course / lesson / module content and you need the teaching to LAND — so grounded, named, and emotionally resonant that the student loves the teacher. Ingests slides/transcripts/notes/outline, extracts the concepts AND the existing narrative spine, finds the abstract/jargon-heavy/ungrounded gaps, then reframes each concept with Russell Brunson's Expert Secrets methodology (Epiphany Bridge, the three false beliefs, the Big Domino, named mental models, story-selling, grounding analogies, future-pacing). Profiles the LEARNER and AUDIENCE first (hard gate). Outputs a per-concept 'landing recipe' and a reworked narrative spine. Triggers: 'make this lesson land', 'teach this concept', 'storytelling for my course', 'expert secrets', 'epiphany bridge', 'mental models for teaching', 'this lesson is too abstract', 'my students aren't getting it', 'name this concept'. NOT slide visuals (that's `presentations`/`design`) and NOT a content-audit/review pass (run review-content first, bring findings here)."
+tags: [course, teaching, storytelling, content]
+recommends: [presentations]
+origin: risco
+---
+
+# Course Storytelling — Make the Teaching Land
+
+*Take a concept the student would forget and turn it into one they can't unhear. Profile the learner first, then run every concept through the Expert Secrets machine: epiphany story → named model → grounded analogy → proof → do-this-now → the so-what.*
+
+This skill owns **the teaching narrative**: extracting what a course actually teaches, finding where it stays abstract, and rebuilding each concept so the realization happens *in the student*, emotionally, not just on the slide. It borrows Russell Brunson's *Expert Secrets* frameworks as a **teaching methodology** (this is method, not text reproduction). The sibling `presentations` skill turns the result into a deck; `marketing` owns sales words; `design` owns pixels; a content-audit/review-content pass audits an existing lesson for gaps before you bring it here.
+
+## When to use / When NOT to use
+
+Use when:
+
+- You have lesson/module/course material (slides, transcript, notes, outline) and the teaching feels flat, abstract, or forgettable.
+- A concept is technically correct but "doesn't click" — students nod and forget.
+- You want a sticky, ownable name + a grounded analogy + a story for an idea.
+- You're sequencing a course and need a belief-building narrative spine, not just a topic list.
+- You want the student to *feel* the epiphany the expert felt, so they trust the teacher.
+
+Do NOT use when (delegate or decline):
+
+- Designing the slide visuals, layout, or exporting a deck → `presentations` (+ `design` for the visual system).
+- Writing sales/landing copy for the course → `marketing`.
+- Auditing an existing lesson for gaps/redundancy/anachronisms with a written report → a content-audit/review-content pass (run it first; bring its findings here).
+- Pure fact-checking or research of the subject matter → `deep-research`.
+
+**Teaching ≠ selling.** Brunson's frameworks here serve comprehension and retention. The "sale" you're closing is *belief in the idea and trust in the teacher* — never bolt a pitch onto a lesson.
+
+## Learner grounding (read this first)
+
+**Hard rule: never reframe or rewrite teaching without a complete learner + audience profile.** Teaching into a void defaults to your AI-median explainer voice — abstract, jargon-true, emotionally dead. The cure is grounding every concept in a real, persisted profile of *who is learning and what must change in them*. An incomplete profile is a hard STOP, not a warning.
+
+Run this gate before reframing a single concept:
+
+1. **Locate the teaching profile.** Read the project's root `CLAUDE.md` and look for a `## Knowledge map` section linking into `02-DOCS/wiki/teaching/` (the `harness` Karpathy-wiki convention: compiled profile articles live under `02-DOCS/wiki/teaching/`, raw inputs the user pastes live under `02-DOCS/raw/teaching/`). If `CLAUDE.md` is absent, the link is missing, or it points nowhere, treat the profile as ABSENT.
+
+2. **Check completeness** against the checklist in `references/learner-grounding.md`. The profile is complete only when every dimension is filled: the LEARNER (level, prior knowledge, pains, desires, current false beliefs, what they want to DO after); the AUDIENCE (same as the buyer or not? live vs recorded? size? context?); the target TRANSFORMATION (the one result, before→after); and constraints/format. **Any empty dimension = INCOMPLETE.**
+
+3. **If ABSENT or INCOMPLETE, STOP and interview the user.** Ask the question script from `references/learner-grounding.md`, **one focused batch at a time** (do not dump all questions at once; ask, wait, persist, then continue). Then:
+   - **a.** Write/update the profile into `02-DOCS/wiki/teaching/` as wiki articles (`learner.md`, `audience.md`, `transformation.md`, `false-beliefs.md`, `constraints.md`, plus an `index.md`), following the article format in `references/learner-grounding.md`. Save any raw material the user pastes (transcripts, outlines, existing slides) verbatim into `02-DOCS/raw/teaching/` and link it from the article's `> Raw:` line. Create the directories if they do not exist.
+   - **b.** Add or update a `## Knowledge map` section in the root `CLAUDE.md` linking to the teaching profile. Create `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet is in `references/learner-grounding.md`.
+
+4. **Only once the profile exists and is complete, proceed.** Cite which articles you used (e.g. "grounded in `02-DOCS/wiki/teaching/learner.md` and `false-beliefs.md`") so every reframing is traceable to a real learner, not an imagined one.
+
+If the user explicitly says "skip the profile, just rough one concept", you may produce a clearly-labelled `DRAFT (ungrounded — not learner-checked)` and still recommend running the gate before anything ships. That is the only exception, and it must be labelled.
+
+Full completeness checklist, the exact batched question script, and the persistence format → `references/learner-grounding.md`.
+
+## The non-negotiables
+
+These are constraints, not preferences. Violating any one is a defect.
+
+1. **Learner profile first.** No reframing before the grounding gate passes (above). Cite the articles you used.
+2. **Every concept gets a story.** A concept taught without a story is a fact the student will forget. Each concept carries at least one Epiphany Bridge beat. (→ `references/brunson-frameworks.md`)
+3. **Every concept gets a name.** An unnamed idea can't be repeated, so it can't be retained. Give each concept a short, ownable, sticky label the student can say out loud. (→ `references/mental-models.md`)
+4. **Every abstraction gets grounded.** No abstract claim ships without a concrete analogy from the learner's own world. "Abstract with no analogy" is a defect. (→ `references/mental-models.md`)
+5. **Break the false belief before installing the new one.** Find the learner's current false belief (vehicle / internal / external), shatter it with a story, *then* teach. Teaching on top of an unbroken false belief bounces off. (→ `references/brunson-frameworks.md`)
+6. **The realization happens in the student.** Tell the epiphany as a journey, don't state the conclusion. The student should *arrive* at the insight, feeling it, not be handed it.
+7. **One Big Domino per module.** Name the single belief that, once believed, makes the rest fall. Build the module to knock it over. (→ `references/brunson-frameworks.md`)
+8. **End every concept on the so-what.** The payoff the student future-paces: what's now possible, what they can do tomorrow. A concept with no so-what is trivia.
+9. **Ground in the learner, not in the expert.** Explain it in the student's world and vocabulary, not the discipline's. Jargon density is a flagged defect. (→ `references/mental-models.md`)
+10. **No fabricated proof or invented credentials.** Stories must be true. If you need a demo/result/proof the user hasn't supplied, mark `[[NEEDS PROOF]]` and ask — never invent a case study or a metric.
+
+## The teaching workflow (one pass)
+
+Run in order. Each step feeds the next; skipping one shows up as a flat lesson downstream.
+
+1. **Ground.** Pass the learner-grounding gate. Load learner, audience, transformation, false beliefs, constraints from `02-DOCS/wiki/teaching/`.
+2. **Analyze the content.** Ingest the material; extract the concept list AND the *existing* narrative spine; map ungrounded / jargon-heavy / story-less gaps. → `references/course-analysis.md`.
+3. **Set the Big Domino.** For the module, name the one belief that makes everything else fall, and sequence concepts to build toward it. → `references/brunson-frameworks.md`, `references/course-analysis.md`.
+4. **Per concept, find the false belief** the learner holds (vehicle / internal / external) and the epiphany that breaks it. → `references/brunson-frameworks.md`.
+5. **Run the landing recipe** for each concept: hook → epiphany-bridge story → named mental model → grounded analogy → proof/demo → application (do-this-now) → so-what. → `references/concept-landing-recipe.md`.
+6. **Name the models.** Engineer a sticky, ownable name + a concrete analogy for each. → `references/mental-models.md`.
+7. **Rewrite the narrative spine.** Resequence the whole module/course as a belief-building arc (the Hero's Two Journeys), not a topic dump. → `references/brunson-frameworks.md`, `references/course-analysis.md`.
+8. **Run the QA gate** (below) and `scripts/verify.sh`. Fix every flag or justify it.
+
+## The Expert Secrets toolkit (applied to teaching)
+
+These are the frameworks you run each concept through. Full templates, scripts, and worked teaching examples → `references/brunson-frameworks.md`. Source-confirmed sequence and naming via Brunson's *Expert Secrets* (see citations in that reference).
+
+- **The Epiphany Bridge.** Tell the story of how *you* (or a relatable character) first realized this — so the student feels the same realization rather than being told the conclusion. Beats: **backstory → the desire → the wall (the struggle) → the epiphany (the "aha") → the new opportunity → the result/transformation.** Emotion first, mechanics second.
+- **The three false beliefs.** Before a student adopts a concept they must drop the belief blocking it. There are exactly three kinds, each broken by its own epiphany story:
+  - **Vehicle** — "this approach/tool/method won't work (for this)."
+  - **Internal** — "even if it works, *I* can't do it."
+  - **External** — "even if I can, something outside me (time, boss, budget, the system) will stop me."
+- **The Big Domino.** The single belief that, if installed, makes every downstream concept fall on its own. Name it per module; aim the whole arc at knocking it over.
+- **Named mental models.** Every concept gets a short, ownable name + a concrete analogy so the student can carry it, repeat it, and reuse it. (→ `references/mental-models.md`)
+- **The Hero's Two Journeys.** The *outer* journey (the skill/result) runs alongside the *inner* journey (the identity shift). Teach both; the inner journey is what makes them love the teacher.
+- **The Attractive Character.** The teacher persona that earns trust: a relatable backstory, admitted flaws, parables, and polarity (a clear point of view). Students bond to a character, not a curriculum.
+- **Story-selling, grounded.** Ground abstractions to earth with concrete analogies/metaphors from the learner's world, "explain it like their day", and future-pacing so the idea becomes tangible enough to click emotionally.
+
+## Analyze the course content
+
+Before reframing, you must *see* what's there. Ingest the material and produce three artifacts. Full method, extraction prompts, and the gap-map template → `references/course-analysis.md`.
+
+1. **Concept inventory** — every distinct idea the material teaches, in teaching order, with a one-line "what the student should be able to DO after this".
+2. **Existing narrative spine** — the story/throughline already present (if any): where it hooks, where it goes flat, whether it builds belief or just stacks topics.
+3. **Gap map** — per concept, flag: `no-story`, `unnamed`, `no-analogy`, `jargon-dense`, `no-application`, `no-so-what`, `belief-not-broken`. These flags drive the rework and mirror exactly what `scripts/verify.sh` greps for.
+
+```text
+GAP MAP (one row per concept)
+concept            | has story? | named? | analogy? | jargon | application? | so-what? | false belief targeted
+-------------------+------------+--------+----------+--------+--------------+----------+----------------------
+"idempotency"      | no         | no     | no       | HIGH   | no           | no       | (none) -> internal
+"retry w/ backoff" | partial    | no     | weak     | MED    | yes          | no       | vehicle
+```
+
+## The landing recipe (per-concept output)
+
+This is the deliverable for every concept. Seven beats, in order. Full template + a fully worked Before→After example → `references/concept-landing-recipe.md`.
+
+```text
+LANDING RECIPE — <concept>
+1. HOOK ............. the tension/question that makes them lean in (open a loop)
+2. EPIPHANY STORY ... backstory -> desire -> wall -> epiphany -> new opportunity -> result
+3. MENTAL MODEL .... the named, ownable idea (a label they can repeat)
+4. GROUNDED ANALOGY  the concrete metaphor from THEIR world that makes it tangible
+5. PROOF / DEMO .... show it working: a demonstration, before/after, or real receipt
+6. APPLICATION ..... do-this-now: the smallest action that makes the idea theirs today
+7. SO-WHAT ......... future-pace the payoff: what's now possible, why it mattered
+```
+
+```text
+Bad  (lecture)  — "Idempotency means an operation can be applied multiple times without
+                   changing the result beyond the initial application."
+Good (landed)   — HOOK: "Ever double-clicked 'Pay' and panicked you'd be charged twice?"
+                  STORY: the night a retry double-charged 4,000 customers...
+                  MODEL: 'The Elevator Button' — pressing it five times still calls one elevator.
+                  ANALOGY: the button's already lit; more presses change nothing.
+                  PROOF: same request ID sent 5x -> one charge (show the log).
+                  APPLICATION: add an idempotency key to your next POST today.
+                  SO-WHAT: you can now retry fearlessly — failures stop being scary."
+```
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "The concept is clear, it doesn't need a story" | Clear ≠ memorable. No story = forgotten by tomorrow. Add an Epiphany Bridge beat. |
+| "Naming it is cutesy / unnecessary" | Unnamed ideas can't be repeated, so they aren't retained. Give it a sticky, ownable name. |
+| "The definition IS the explanation" | A definition is the *destination*; the student needs the *journey* to arrive there. Ground it with an analogy. |
+| "My audience is technical, skip the analogy" | Experts forgot they once didn't know. Analogy speeds the click for everyone; jargon density is a defect. |
+| "I'll just tell them the insight" | Told insight bounces off; *arrived-at* insight sticks. Make the realization happen in them. |
+| "Teach the right way first, address doubts later" | An unbroken false belief deflects the lesson. Break vehicle/internal/external *before* installing. |
+| "Every lesson is equally important" | No — one Big Domino per module makes the rest fall. Find it; aim the arc at it. |
+| "End on the summary" | Summaries are forgettable; future-paced so-whats are not. End on what's now possible. |
+| "I'll invent a quick case study to prove it" | Never. Stories must be true. Mark `[[NEEDS PROOF]]` and ask the user. |
+| "Just teach the skill (outer journey)" | The inner journey (identity shift) is why they love the teacher. Teach both. |
+
+## Quick reference
+
+| Lever | Default | Where |
+| --- | --- | --- |
+| Story per concept | mandatory — ≥1 Epiphany Bridge beat | `references/brunson-frameworks.md` |
+| Epiphany beats | backstory → desire → wall → epiphany → new opportunity → result | `references/brunson-frameworks.md` |
+| False beliefs | break vehicle + internal + external before teaching | `references/brunson-frameworks.md` |
+| Big Domino | one per module; aim the arc at it | `references/brunson-frameworks.md` |
+| Named model | short, ownable, repeatable; one per concept | `references/mental-models.md` |
+| Analogy | concrete, from the learner's world | `references/mental-models.md` |
+| Recipe beats | hook → story → model → analogy → proof → application → so-what | `references/concept-landing-recipe.md` |
+| Jargon | flagged when dense / unglossed | `scripts/verify.sh` |
+| End on | the so-what (future-paced payoff) | `references/concept-landing-recipe.md` |
+| Profile | hard gate before any rework | `references/learner-grounding.md` |
+
+## Teaching QA gate ("did it land?")
+
+Run before claiming done. `scripts/verify.sh` automates the greppable subset.
+
+- [ ] Learner + audience profile located, complete, and cited (which articles grounded this).
+- [ ] Big Domino named for the module; the arc is sequenced to knock it over.
+- [ ] Every concept has ≥1 story (Epiphany Bridge beat) — no `no-story` lessons.
+- [ ] Every concept has a named, ownable mental model.
+- [ ] Every abstraction has a concrete analogy from the learner's world.
+- [ ] The targeted false belief (vehicle / internal / external) is named and broken before the concept is installed.
+- [ ] Every concept ends with an application (do-this-now) and a so-what (future-paced payoff).
+- [ ] Jargon is glossed or grounded; no unexplained term-dumps.
+- [ ] The insight is *arrived at*, not stated; the realization happens in the student.
+- [ ] Both journeys present: the skill (outer) and the identity shift (inner).
+- [ ] No fabricated stories, proof, metrics, or credentials; gaps marked `[[NEEDS PROOF]]`.
+- [ ] The reworked narrative spine builds belief, it doesn't just stack topics.
+
+Automate → `scripts/verify.sh` (read-only; warns by default, `--strict` to gate CI).
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+This skill's 02-DOCS record has two parts, both indexed from a `## Knowledge map` section in the root `CLAUDE.md`:
+
+- The **learner + audience profile** at `02-DOCS/wiki/teaching/` — a hard gate (see "Learner grounding" above): if the root `CLAUDE.md` lacks the link or any dimension is empty (learner, audience, transformation, false beliefs, constraints), ask until complete, persist it (raw inputs to `02-DOCS/raw/teaching/`), link it from `## Knowledge map` (create `CLAUDE.md` if absent), and only then teach.
+- The **course teaching conventions** at `02-DOCS/wiki/stack/course-storytelling.md` (or alongside the profile under `02-DOCS/wiki/teaching/`) — the established narrative spine, the named mental models already coined, the Big Dominoes per module, and the teacher's Attractive Character. Recorded, not gated.
+
+Create/update both as decisions are made and refresh their `CLAUDE.md` links. Read them first on every use and keep every reframing consistent with them. If the project has no `02-DOCS` layer at all, skip this section silently and proceed with the in-session profile.
+
+## See Also
+
+- `../marketing/SKILL.md` — the WORDS that sell the course (value prop, landing copy, launch emails). This skill teaches; that one sells.
+- `../presentations/SKILL.md` — turn the landed lesson into a deck (Marp/Slidev/PPTX, speaker notes).
+- `../design/SKILL.md` — the visual system and pixels behind the slides/diagrams.
+- A content-audit / review-content pass — audit an existing lesson/module/notebook for gaps, redundancy, anachronisms, and storytelling problems (run it first; bring its report here). This skill rebuilds; that pass diagnoses.
+- `../harness/SKILL.md` — the `02-DOCS` Karpathy-wiki convention this skill persists the teaching profile into.
+- References: `references/brunson-frameworks.md`, `references/learner-grounding.md`, `references/mental-models.md`, `references/course-analysis.md`, `references/concept-landing-recipe.md`.