@damiangilgonzalez/harness 1.3.7

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 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 '*/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,137 @@
+---
+name: course-storytelling
+description: "Use when lesson or course content is correct but forgettable and a concept has to LAND: profiles the learner, breaks the blocking false belief, then rebuilds it as epiphany story → named model → grounded analogy → proof → so-what. NOT outcomes, assessment or module order (that is `course-builder`), NOT slide visuals (that is `presentations`)."
+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).
+
+Boundaries: `course-builder` decides what the course must prove — outcomes, assessment, module order — and hands you the skeleton; this skill makes each concept inside it land. `presentations` turns the landed lesson into a deck, `design` owns the pixels, `marketing` owns the words that sell the course, and a content-audit/review-content pass diagnoses an existing lesson (run it first, bring its findings here — that pass audits, this one rebuilds).
+
+**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 (hard gate — read this first)
+
+**Never reframe teaching without a complete learner + audience profile.** Teaching into a void defaults to your AI-median explainer voice — abstract, jargon-true, emotionally dead. An incomplete profile is a hard STOP, not a warning, because everything downstream (which false belief to break, which analogy lands) is derived from it.
+
+1. **Locate the profile.** Read the root `CLAUDE.md`, follow its `## Knowledge map` pointer to `docs/wiki/index.md`, and look for the entry into `docs/wiki/teaching/` (the `harness` Karpathy-wiki convention: compiled articles in `docs/wiki/teaching/`, raw user-pasted material in `docs/raw/teaching/`). No `CLAUDE.md`, no index entry, or a pointer that goes nowhere = ABSENT.
+2. **Check completeness** against the checklist in `references/learner-grounding.md`: the LEARNER (level, prior knowledge, pains, desires, current false beliefs, what they DO after), the AUDIENCE (same as the buyer? live vs recorded? size? context?), the target TRANSFORMATION (one result, before→after), and constraints/format. **Any empty dimension = INCOMPLETE.**
+3. **If ABSENT or INCOMPLETE, STOP and interview** with the batched question script in `references/learner-grounding.md` — one focused batch at a time, wait, persist, continue. Then write the profile as wiki articles under `docs/wiki/teaching/` (`learner.md`, `audience.md`, `transformation.md`, `false-beliefs.md`, `constraints.md`, `index.md`), save pasted transcripts/outlines/slides verbatim under `docs/raw/teaching/` and link them from each article's `> Raw:` line, index the profile in `docs/wiki/index.md`, and ensure root `CLAUDE.md` carries the short pointer to that index (create it if absent; additive only). Article format and the exact `CLAUDE.md` snippet → `references/learner-grounding.md`.
+4. **Only then proceed**, citing which articles you used ("grounded in `docs/wiki/teaching/learner.md` and `false-beliefs.md`") so every reframing is traceable to a real learner, not an imagined one.
+
+Sole exception: if the user explicitly says "skip the profile, just rough one concept", produce a clearly-labelled `DRAFT (ungrounded — not learner-checked)` and still recommend running the gate before anything ships.
+
+## 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 gate above. Load learner, audience, transformation, false beliefs, constraints from `docs/wiki/teaching/` and cite them.
+2. **Analyze the content.** Ingest the material; extract the concept list AND the *existing* narrative spine; map the ungrounded / jargon-heavy / story-less gaps. → `references/course-analysis.md`.
+3. **Set the Big Domino.** Name the one belief per module that makes everything else fall, and sequence concepts to build toward it — not every lesson is equally important. → `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. Break it *before* teaching: a lesson landing on an unbroken false belief bounces off. → `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. Every concept gets all seven; a concept with no story is forgotten by tomorrow, and one with no so-what is trivia. → `references/concept-landing-recipe.md`.
+6. **Name the models.** Engineer a sticky, ownable name + a concrete analogy for each — an unnamed idea can't be repeated, so it can't be retained, and an abstraction with no analogy from the learner's own world is a defect. → `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.
+
+Throughout: tell the epiphany as a journey so the student *arrives* at the insight rather than being handed the conclusion, explain it in the student's vocabulary instead of the discipline's, and **never invent proof** — if a demo, result, metric or credential wasn't supplied by the user, mark it `[[NEEDS PROOF]]` and ask.
+
+## 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 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
+
+| Anti-pattern | 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. |
+
+## Teaching QA gate ("did it land?")
+
+Run before claiming done. `scripts/verify.sh` automates the greppable subset (read-only; warns by default, `--strict` to gate CI).
+
+- [ ] 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.
+
+## Project grounding (docs)
+
+Beyond the gated learner profile, record the **course teaching conventions** at `docs/wiki/stack/course-storytelling.md` (or alongside the profile under `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 — update it as decisions are made, keep its entry current in `docs/wiki/index.md`, read it first on every use, and keep every reframing consistent with it. The wiki convention itself belongs to `../harness/SKILL.md`. If the project has no `docs` layer, skip this silently and proceed with the in-session profile.

package/skills/course-storytelling/evals/README.md

@@ -0,0 +1,54 @@
+# Eval harness — `course-storytelling`
+
+This is an **agent-run** eval, not a shell script. You drive a Claude Code agent
+(or equivalent) and judge its behaviour against `cases.yaml`. There is no
+automated grader here; a human or a judge-agent reads the transcript and scores it.
+
+`cases.yaml` has three blocks: `should_trigger` (6), `should_not_trigger` (5),
+and `capability` (2 scenarios with rubrics).
+
+## A. Triggering accuracy
+
+Goal: the skill fires on real teaching-narrative work and stays quiet on near-misses.
+
+1. Load **only** `course-storytelling` into the agent (no sibling skills loaded,
+   so a miss can't be masked by another skill picking up the slack).
+2. For **each** prompt in `should_trigger` and `should_not_trigger`, start a fresh
+   session and paste the prompt verbatim. Run **3–5 trials** per prompt (the
+   trigger decision is stochastic).
+3. Record per trial:
+   - `should_trigger` → PASS if the agent invokes/announces `course-storytelling`.
+   - `should_not_trigger` → PASS if it does **not** invoke it. Bonus: it routes to
+     the `route_to` sibling named in the case (or correctly declines when `none`).
+4. **Pass bar: ≥90% correct decisions** across all trials (both blocks combined).
+   Any prompt that fails on a majority of its trials is a real defect — fix the
+   SKILL.md description/trigger list, don't loosen the case.
+
+## B. Capability uplift (with vs without)
+
+Goal: the skill **measurably improves** the teaching output, not just fires.
+
+1. For each `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (baseline — agent answers from general knowledge).
+   - **WITH** `course-storytelling` loaded.
+2. Score each output against that scenario's `must_include` rubric: fraction of
+   checkable points actually present.
+3. **Pass bar:**
+   - WITH the skill: **≥80% of rubric points covered.**
+   - The WITH score must **clearly beat** WITHOUT (expect the baseline to skip the
+     learner-grounding gate, invent proof, state the insight instead of building an
+     epiphany, and end on a summary — all rubric misses).
+   - Scenario 2 specifically checks the **hard STOP**: without the skill the agent
+     will usually just answer; with it, it must refuse-and-interview first.
+
+## Honesty notes
+
+- Trials are stochastic — report the actual trial counts and pass rates, don't
+  round a 2/5 up to "passes".
+- A `should_not_trigger` that fires is as much a defect as a `should_trigger` that
+  misses; both go in the report.
+- If a case is wrong (ambiguous prompt, sibling overlap is genuinely 50/50), fix
+  `cases.yaml` and say so — don't quietly grade around it.
+- Capability grading is judgement, not grep. The `scripts/verify.sh` in the skill
+  only covers the greppable subset (jargon/story/name flags); the rubric here is
+  the real bar.

package/skills/course-storytelling/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: course-storytelling
+
+should_trigger:
+  - prompt: "This lesson on database indexing is technically correct but my students just nod and forget it the next day. Can you make it actually land?"
+    why: "Core trigger: correct-but-doesn't-click teaching content, explicit 'make it land' intent. This is exactly the abstract/forgettable-lesson case the skill owns."
+  - prompt: "I'm teaching idempotency in my backend course and it stays super abstract. Help me reframe it with an epiphany bridge and a sticky name students can repeat."
+    why: "Names the Expert Secrets / Epiphany Bridge methodology and the 'name the concept' + grounding goals — the skill's explicit trigger phrases."
+  - prompt: "I have the full transcript and slides for module 3 of my course. The teaching feels flat — I want it rebuilt so the realization happens in the student, not just stated on the slide."
+    why: "Ingests course material (transcript/slides), flat/forgettable teaching, wants the insight arrived-at not stated — the skill's narrative-rebuild workflow, not a visual or audit task."
+  - prompt: "Help me sequence my whole onboarding course so each module builds belief toward one core idea instead of being a random list of topics."
+    why: "Belief-building narrative spine + Big Domino sequencing across a course — the skill owns the teaching narrative arc, not just per-slide design."
+  - prompt: "My learners keep resisting this concept — they think 'this won't work for my stack' before I even explain it. How do I get them past that so the lesson actually sticks?"
+    why: "Non-obvious phrasing: doesn't name the tool. This is a vehicle false-belief that must be broken before teaching — the skill's break-the-false-belief-first non-negotiable."
+  - prompt: "Can you turn this dry explanation of OAuth flows into something memorable with a real-world analogy and a story so people don't tune out?"
+    why: "Grounding an abstraction with a concrete analogy + story to make teaching memorable — story-selling/grounded-analogy core, without naming Brunson explicitly."
+
+should_not_trigger:
+  - prompt: "Take my landed OAuth lesson and build a Marp slide deck with speaker notes and a clean layout."
+    route_to: "presentations"
+    why: "This is turning finished teaching into a deck — slide visuals/layout/export. The skill explicitly delegates deck-building to presentations."
+  - prompt: "Write the landing-page copy and launch email sequence to sell my course."
+    route_to: "marketing"
+    why: "Sales/landing copy for the course is marketing's domain. The skill teaches; it never bolts a pitch on, and explicitly defers selling words to marketing."
+  - prompt: "Audit module 14 of my course for gaps, redundancy, anachronisms, and outdated stack references, and give me a written report."
+    route_to: "external:review-content"
+    why: "Diagnostic content-audit pass with a written report. The skill says run review-content first and bring findings here; it rebuilds, it does not audit."
+  - prompt: "Design a color system, typography scale, and diagram style for my course slides."
+    route_to: "design"
+    why: "Pure visual system / pixels. The skill defers the visual layer to design; it owns narrative, not aesthetics."
+  - prompt: "Fact-check whether the historical claims in my lesson about the origins of TCP are actually accurate, with sources."
+    route_to: "research-ops"
+    why: "Pure fact-checking/research of subject matter, not reframing teaching. The skill forbids inventing proof and defers verification to a research pass — `research-ops` in this catalog, a deep-research tool where the environment provides one."
+
+capability:
+  - scenario: "A learner profile already exists and is complete in docs/wiki/teaching/. The user gives a flat, definition-only lesson on 'idempotency' for a mid-level backend course and asks to make it land."
+    must_include:
+      - "Cites/loads the learner + audience profile first (e.g. references docs/wiki/teaching/learner.md and false-beliefs.md) before reframing"
+      - "Names the specific false belief being broken and tags it vehicle, internal, or external, breaking it before teaching the concept"
+      - "Produces an Epiphany Bridge story with the beats backstory -> desire -> wall -> epiphany -> new opportunity -> result, so the realization happens in the student rather than being stated"
+      - "Coins a short, sticky, ownable name for the concept plus a concrete analogy from the learner's world (not the discipline's jargon)"
+      - "Follows the seven-beat landing recipe: hook -> story -> mental model -> grounded analogy -> proof/demo -> application(do-this-now) -> so-what"
+      - "Ends on a future-paced so-what and includes a do-this-now application, not a summary"
+      - "Marks any proof/metric the user did not supply as [[NEEDS PROOF]] instead of inventing a case study or number"
+  - scenario: "User asks to make a lesson land but no learner profile exists yet (no CLAUDE.md Knowledge map / no docs/wiki/teaching/)."
+    must_include:
+      - "Treats the profile as ABSENT and STOPS rather than reframing into a void"
+      - "Interviews the user with a focused batch of questions (not all at once) covering learner level/prior-knowledge/pains/desires/false-beliefs, audience, target transformation, and constraints"
+      - "States it will persist the profile into docs/wiki/teaching/ (learner.md, audience.md, transformation.md, false-beliefs.md, constraints.md, index.md) and raw inputs into docs/raw/teaching/"
+      - "Will add/update a ## Knowledge map link in the root CLAUDE.md (additive, create if absent)"
+      - "Only proceeds to reframe after the profile is complete, OR if the user insists on skipping, emits a clearly-labelled DRAFT (ungrounded — not learner-checked)"