rsc-universal 0.1.1

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: "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: "deep-research"
+    why: "Pure fact-checking/research of subject matter, not reframing teaching. The skill forbids inventing proof and defers verification to deep-research."
+
+capability:
+  - scenario: "A learner profile already exists and is complete in 02-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 02-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 02-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 02-DOCS/wiki/teaching/ (learner.md, audience.md, transformation.md, false-beliefs.md, constraints.md, index.md) and raw inputs into 02-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)"

package/skills/course-storytelling/references/brunson-frameworks.md

@@ -0,0 +1,190 @@
+# Brunson Frameworks — Expert Secrets, Applied to Teaching
+
+The *Expert Secrets* toolkit (Russell Brunson) repurposed for **comprehension and retention**, not for closing a sale. Each framework below is a teaching move: a way to make the realization happen *in the student* so the idea sticks and the student trusts the teacher. This is methodology — patterns and scripts you fill with the teacher's own true material, never reproduced text.
+
+> Framework names and sequence confirmed against Brunson's *Expert Secrets*: the Epiphany Bridge, the Big Domino, the three false-belief patterns (vehicle / internal / external), the Hero's Two Journeys, and the Attractive Character. Summaries: [Shortform — Epiphany Bridge](https://www.shortform.com/blog/russell-brunson-epiphany-bridge/), [Dan Silvestre — Expert Secrets summary](https://dansilvestre.com/summaries/expert-secrets-summary/), [ReadingGraphics — Expert Secrets](https://readingraphics.com/book-summary-expert-secrets-russell-brunson/).
+
+The SKILL.md runtime invokes these; this file holds the templates + worked teaching examples.
+
+---
+
+## 1. The Epiphany Bridge
+
+The single most important teaching move. Instead of *stating* the conclusion ("idempotency makes retries safe"), you tell the story of how someone first *realized* it, so the student lives the realization and arrives at the conclusion themselves — feeling it.
+
+### Why it works for teaching
+
+A stated fact enters as information and is forgotten. A story is rehearsed by the listener's brain as lived experience; the emotion tags it for retention. You are not decorating the concept with a story — the story *is* the delivery vehicle for the belief.
+
+### The six beats
+
+```text
+EPIPHANY BRIDGE (fill with a TRUE story — teacher's own, a student's, or a documented case)
+1. BACKSTORY ......... who/where, the ordinary situation before — relatable, specific
+2. THE DESIRE ........ what they wanted (the goal that pulls the story forward)
+3. THE WALL .......... the struggle / the thing that kept failing (the pain, felt)
+4. THE EPIPHANY ...... the "aha" — the moment the new way revealed itself
+5. NEW OPPORTUNITY ... the new approach the epiphany opened up (= the concept you're teaching)
+6. THE RESULT ........ the transformation it produced (proof + the so-what)
+```
+
+### Rules
+
+- **Emotion before mechanics.** Tell the feeling of the wall before the technical fix. The student must *want* the epiphany.
+- **Show the struggle honestly.** The wall must be real and a little embarrassing. A frictionless story teaches nothing.
+- **Land on the concept at beat 5.** The "new opportunity" IS the thing you're teaching — that's the handoff from story to mental model.
+- **Keep it true.** Use the teacher's real story, a real student's, or a documented case. If none exists, mark `[[NEEDS PROOF]]` and ask — never fabricate.
+
+### Worked teaching example — "idempotency"
+
+```text
+1. BACKSTORY:  "Two years in, I owned the payments service. 4am, on-call."
+2. DESIRE:     "I just wanted the failed charges to retry automatically so I could sleep."
+3. WALL:       "The retry fired before the first response came back. We charged 4,000 people twice.
+                Refunds, apologies, a very long morning."
+4. EPIPHANY:   "The senior eng asked one question: 'What if the second request just... did nothing?'
+                That reframed everything. The problem wasn't retrying — it was that the server
+                couldn't tell 'try again' from 'do it again'."
+5. NEW OPP:    "That's idempotency: design the operation so doing it five times equals doing it once."
+6. RESULT:     "We added an idempotency key. Retries became free. I slept. Nobody got double-charged
+                again." (-> hands off to the named model: 'The Elevator Button')
+```
+
+```text
+Bad  — "Idempotency is the property that f(f(x)) = f(x)." (definition first, no one cares yet)
+Good — the six-beat story above, THEN the definition lands because they want it.
+```
+
+---
+
+## 2. The three false beliefs (break before you build)
+
+Before a student adopts a concept, they must drop the belief that's blocking it. Teaching on top of an unbroken false belief bounces off — they nod and don't change. There are exactly **three** kinds, each broken by its own mini Epiphany Bridge.
+
+| Belief type | The student's silent objection | What breaks it |
+| --- | --- | --- |
+| **Vehicle** | "This approach/tool/method doesn't actually work (for this)." | A story where the vehicle worked when nothing else did. |
+| **Internal** | "Even if it works, *I'm* not the kind of person who can do it." | A story of someone just like them who did it (or you, before you could). |
+| **External** | "Even if I can, something outside me will stop it (time, budget, my boss, the legacy system)." | A story where the external wall fell or got routed around. |
+
+### How to use it
+
+1. From the learner profile (`02-DOCS/wiki/teaching/false-beliefs.md`), pull the belief actually blocking *this* concept.
+2. Identify which of the three types it is.
+3. Pick the matching epiphany story and tell it *first* — clear the block — then install the concept.
+
+### Worked example — concept "write tests first (TDD)"
+
+```text
+VEHICLE false belief:  "Tests just slow me down; they don't catch real bugs."
+  -> Story: the refactor that would've shipped a data-loss bug, caught only because a test
+     written first failed loudly. The vehicle (TDD) worked when review and manual QA didn't.
+
+INTERNAL false belief: "Good engineers can do TDD; I just hack until it works."
+  -> Story: you, year one, convinced TDD was for "real" engineers — until one boring CRUD feature
+     where writing the test first made you faster, and you realized it's a habit, not a talent.
+
+EXTERNAL false belief: "My team/deadline won't let me write tests first."
+  -> Story: the sprint where the deadline was the reason TO do it — the test became the spec,
+     cut the back-and-forth, and shipped early. The external wall was the excuse, not the cause.
+```
+
+Break all three that apply. A concept can be blocked by one or by all three; address each that the learner profile flags.
+
+---
+
+## 3. The Big Domino
+
+The **one belief** that, if the student fully accepts it, makes every other concept in the module fall on its own. You don't have to win every micro-argument — you have to knock over the Big Domino.
+
+### Finding it
+
+Ask: *"If they believed only ONE thing after this module, which belief would make all the rest obvious?"* That's the domino. Everything in the module is either the story that knocks it over or a consequence that falls after it.
+
+```text
+BIG DOMINO statement (one sentence, a belief — not a topic)
+"If I [adopt this one idea], then [the hard thing] becomes [easy/safe/possible]."
+```
+
+### Worked examples
+
+```text
+Module: "Reliability"        Domino: "If I make every operation safe to retry, outages stop being scary."
+Module: "Teaching"           Domino: "If I make the student arrive at the insight, they never forget it."
+Module: "Personal finance"   Domino: "If I automate the saving before I can spend it, willpower stops mattering."
+```
+
+Once the domino is set, sequence the module as the arc that topples it (see the Hero's Two Journeys below and `course-analysis.md` for resequencing).
+
+---
+
+## 4. The Hero's Two Journeys
+
+Every lesson runs two journeys in parallel. Teach both; the inner one is why the student loves the teacher.
+
+| Journey | What it is | What the student gets |
+| --- | --- | --- |
+| **Outer** | The skill, the result, the mechanics ("how to do X") | Competence — they can DO the thing |
+| **Inner** | The identity shift ("I'm now the kind of person who…") | Belief — they SEE themselves differently |
+
+```text
+Bad  (outer only)  — "Here's the retry-with-backoff algorithm. Memorize the formula."
+Good (both)        — outer: the backoff algorithm + a demo;
+                     inner: "You stop being the person who fears the pager and become the one
+                     who ships resilient systems on purpose." (the identity shift = why they care)
+```
+
+The student is the hero. The teacher is the **guide** who already walked the road — which is the bridge to the next framework.
+
+---
+
+## 5. The Attractive Character (the teacher persona)
+
+Students bond to a character, not a curriculum. The Attractive Character is the trustworthy guide persona the teaching is delivered through. Four levers:
+
+- **Relatable backstory** — the teacher was once where the student is now (the "before" of the transformation). Establishes the guide earned the road.
+- **Admitted flaws** — the double-charge, the year of avoiding TDD, the thing you got wrong. Flaws make the guide trustworthy and the student's struggle normal.
+- **Parables** — short repeatable stories that each carry one lesson (the epiphany bridges become the parables).
+- **Polarity** — a clear point of view. A teacher who stands for something ("tests are a design tool, not a chore") is memorable; a neutral one is wallpaper. Polarity attracts the right students and is fine to repel the wrong fit.
+
+```text
+Bad  — neutral, omniscient narrator: "One should always validate inputs."
+Good — "I learned input validation the day a single emoji in a username took down prod.
+        I'm paranoid about it now, and you should be too." (backstory + flaw + polarity)
+```
+
+Persist the chosen Attractive Character in `02-DOCS/wiki/teaching/` so the persona stays consistent across every lesson.
+
+---
+
+## 6. Story-selling, grounded (abstraction → earth)
+
+Brunson's story-selling, used to make abstractions *tangible* rather than to sell. The mechanics of analogy/metaphor engineering live in `mental-models.md`; the teaching moves here are:
+
+- **Explain it in their world.** Translate the concept into the learner's daily vocabulary and objects (from `02-DOCS/wiki/teaching/learner.md`), not the discipline's.
+- **Future-pace.** Walk the student through a near-future moment where they use the idea and it pays off ("Next time a deploy fails at 5pm, you'll…"). The brain pre-experiences the win and wants it.
+- **One idea per story.** A parable that teaches three things teaches none. Split it.
+
+---
+
+## Putting it together (per concept)
+
+```text
+1. From the profile, name the false belief blocking this concept (vehicle / internal / external).
+2. Tell the matching Epiphany Bridge to break it (six beats).
+3. The "new opportunity" beat hands off to the named mental model (-> mental-models.md).
+4. Ground the model with a concrete analogy from the learner's world.
+5. Show proof (demo / before-after / receipt) — true only.
+6. Run both journeys: the skill (outer) and the identity shift (inner).
+7. Keep one Big Domino per module in view; this concept is a step toward toppling it.
+```
+
+This is the engine behind the per-concept landing recipe → `concept-landing-recipe.md`.
+
+## See Also
+
+- `../SKILL.md` — the runtime that invokes these frameworks and the non-negotiables.
+- `mental-models.md` — naming + analogy engineering for the "new opportunity" handoff.
+- `concept-landing-recipe.md` — the seven-beat per-concept output these frameworks feed.
+- `learner-grounding.md` — where the false beliefs and transformation come from.
+- `course-analysis.md` — resequencing the module as the arc that topples the Big Domino.

package/skills/course-storytelling/references/concept-landing-recipe.md

@@ -0,0 +1,136 @@
+# Concept Landing Recipe — The Per-Concept Output Template
+
+This is the deliverable. For every concept that survives the gap map (`course-analysis.md`), you produce one landing recipe: seven beats, in order, that take the student from "don't care / don't believe" to "I get it, I can do it, and I love whoever taught me this." It's the assembly line that runs the Brunson frameworks (`brunson-frameworks.md`) and the named models (`mental-models.md`) into a single shippable lesson unit.
+
+---
+
+## The seven beats
+
+```text
+LANDING RECIPE — <concept name>
+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 (the label they 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
+```
+
+### What each beat must do
+
+| Beat | Job | Fails if |
+| --- | --- | --- |
+| **Hook** | Open a curiosity/tension loop in the student's world | It's an agenda slide or a definition |
+| **Epiphany story** | Make the realization happen *in* them (6 beats, true) | The conclusion is stated, not arrived at |
+| **Mental model** | Give a sayable, picturable, ownable name | Unnamed, or named in jargon |
+| **Grounded analogy** | Map the mechanism onto something they know | Vibe-only; parts don't correspond |
+| **Proof / demo** | Show it's real, not just plausible | Asserted, or fabricated |
+| **Application** | Smallest action that makes it theirs today | "Go practice" with no concrete first step |
+| **So-what** | Future-pace the payoff; close the loop | Ends on a recap/summary |
+
+### Ordering rules
+
+- **Hook before story.** Earn the lean-in before you spend their attention on a story.
+- **Story before model.** The model's name only sticks if it's the punchline of a story they felt.
+- **Break the belief inside the story.** The wall + epiphany beats do the false-belief work (→ `brunson-frameworks.md`); don't bolt on a separate "objection handling" section.
+- **Analogy after the name, not instead of it.** Name first (so they can repeat it), then make it concrete.
+- **Application before so-what.** Let them act, *then* feel the future payoff of having acted.
+
+---
+
+## Fully worked example — Before → After
+
+A dry, accurate, forgettable lesson on a real concept, rebuilt into one the student loves.
+
+### BEFORE (the flat lesson — every gap-map flag fires)
+
+```text
+Concept: Idempotency
+
+Idempotency is a property of certain operations in computer science whereby they can be
+applied multiple times without changing the result beyond the initial application. In the
+context of HTTP, methods such as GET, PUT, and DELETE are idempotent, whereas POST is not.
+To make a POST endpoint idempotent, one can use an idempotency key supplied by the client,
+which the server stores and uses to deduplicate requests. This is important for reliability.
+```
+
+Why it fails: `no-story`, `unnamed`, `no-analogy`, `jargon-dense` (idempotency, HTTP methods, deduplicate), `no-application`, `no-so-what`, and it never breaks the student's false belief that "retrying is dangerous." It's correct and dead.
+
+### AFTER (the landed lesson — seven beats)
+
+```text
+1. HOOK
+   "Have you ever double-clicked a 'Pay' button, then sat there sweating, wondering if you just
+    paid twice? Hold that feeling — because your users feel it about YOUR system every day."
+
+2. EPIPHANY STORY  (six beats, true)
+   - Backstory: "Two years in, I owned payments. 4am, on call."
+   - Desire:    "I just wanted failed charges to retry on their own so I could sleep."
+   - Wall:      "My retry fired before the first response came back. We charged 4,000 people twice.
+                 Refunds, apology emails, the worst morning of my career."  (breaks the INTERNAL
+                 belief 'I can't be trusted with retries' — it's not you, it's the design)
+   - Epiphany:  "A senior eng asked one question: 'What if the second request just... did nothing?'
+                 The bug wasn't retrying. It was that the server couldn't tell 'try again' from
+                 'do it again.'"
+   - New opp:   "Design the operation so doing it five times equals doing it once."
+   - Result:    "We shipped one idempotency key. Retries became free. I slept."
+
+3. MENTAL MODEL
+   "The Elevator Button. That's the whole idea. Remember it by that name."
+
+4. GROUNDED ANALOGY
+   "Press the elevator call button. It lights up; one elevator is coming. Now press it five more
+    times. Still one elevator. The button already knows it's been pressed — extra presses change
+    nothing. An idempotency key is that 'already lit' state for your API: the first request lights
+    it; duplicates see the light and do nothing.
+    (Where it breaks: a real elevator comes no matter what; your API needs the KEY to recognize the
+    duplicate — that recognition is the part you build.)"
+
+5. PROOF / DEMO
+   "Watch: I send the same request with the same idempotency key five times." [show the log]
+   "Five requests in. One charge out. Here's the dedupe in the response — same charge ID every time."
+
+6. APPLICATION  (do-this-now)
+   "Before you close this lesson: open your most dangerous POST endpoint — the one that moves money
+    or sends something. Add one header: `Idempotency-Key`. Store it, check it before you act. That's
+    your first idempotent endpoint, today."
+
+7. SO-WHAT  (future-pace)
+   "Next time a deploy fails at 5pm and the retries start firing, you won't lunge for the kill switch.
+    You'll watch them retry, safely, and go home. You just stopped being the engineer who fears the
+    pager and became the one who builds systems that forgive themselves."
+```
+
+```text
+Notice what changed:
+- The DEFINITION still appears — but at beat 2's "new opportunity", AFTER they want it.
+- Jargon ('deduplicate', 'HTTP methods') is replaced by the elevator picture.
+- The student leaves with a NAME they'll repeat, a first ACTION, and an identity shift.
+- Both journeys are present: the skill (add a key) and the identity ("the one who...").
+```
+
+---
+
+## Assembling a module
+
+Run the recipe per concept, then thread them on the reworked narrative spine from `course-analysis.md`:
+
+```text
+MODULE OUTPUT
+- Big Domino: <the one belief>            (e.g. "retry fearlessly: outages stop being scary")
+- Opening hook: <module-level lean-in>
+- Concept 1 landing recipe  (breaks belief A) ─┐
+- Concept 2 landing recipe  (breaks belief B)  ├─ each topples a domino toward the Big Domino
+- Concept 3 landing recipe  (breaks belief C) ─┘
+- Closing future-pace: <who they've become + what they can now do>
+```
+
+Then run the QA gate in `SKILL.md` and `scripts/verify.sh`. Every gap-map flag that fired in the BEFORE must be cleared in the AFTER.
+
+## See Also
+
+- `../SKILL.md` — the seven-beat recipe is the skill's core deliverable; the QA gate checks it.
+- `brunson-frameworks.md` — the Epiphany Bridge (beat 2) and false-belief breaks inside the story.
+- `mental-models.md` — the named model (beat 3) and grounded analogy (beat 4) craft.
+- `course-analysis.md` — the gap map that decides which concepts need a recipe, and the spine that threads them.

package/skills/course-storytelling/references/course-analysis.md

@@ -0,0 +1,124 @@
+# Course Analysis — Ingest, Extract, Map Gaps, Sequence for Belief
+
+Before you can make teaching land, you have to *see* what's there: what the material actually teaches, the story it already tells (if any), and exactly where it goes flat. This file is the analysis pass that runs after grounding and before reframing (step 2 of the SKILL.md workflow). It produces three artifacts — concept inventory, existing narrative spine, gap map — and then resequences the whole module into a belief-building arc.
+
+---
+
+## Step 1 — Ingest the material
+
+Accept whatever the user has: slides, a transcript, lecture notes, a one-line outline, a notebook. Save anything pasted verbatim into `02-DOCS/raw/teaching/` (see `learner-grounding.md`), then read for structure, not polish.
+
+```text
+INGEST CHECKLIST
+[ ] Identify the unit: is this one lesson, a module, or a whole course? (sets the Big Domino scope)
+[ ] Note the medium and length budget (from wiki/teaching/constraints.md)
+[ ] Find the implied teaching order (what comes before what)
+[ ] Flag anything that's actually missing (a concept referenced but never taught)
+```
+
+If the material is thin (just an outline), extract the *intended* concepts and treat every beat as a gap to fill rather than a thing to rework.
+
+---
+
+## Step 2 — Concept inventory
+
+List every distinct idea the material teaches, in teaching order, each with a one-line "what the student should be able to DO after this" (pulled from / checked against `wiki/teaching/learner.md`'s "do after").
+
+```text
+CONCEPT INVENTORY
+#  | concept              | what the student can DO after
+---+----------------------+-------------------------------------------------
+1  | idempotency          | add an idempotency key to a POST and explain why
+2  | retry with backoff   | configure jittered backoff instead of fixed retries
+3  | circuit breaker      | wrap a flaky dependency so it fails fast, not slow
+```
+
+Rules:
+
+- **One concept per row.** If a "concept" needs two "do" lines, it's two concepts — split it.
+- **DO, not KNOW.** "Understand retries" is not a row; "configure jittered backoff" is. Capability is the unit.
+- **Mark dependencies.** Note which concepts presuppose an earlier one — this drives sequencing.
+
+---
+
+## Step 3 — Extract the existing narrative spine
+
+Most material already has *some* throughline, even if accidental. Find it and judge it honestly.
+
+```text
+SPINE EXTRACTION
+- Opening: how does it start? (hook / cold definition / agenda slide?)
+- Throughline: is there a story or just a topic stack?
+- Belief work: does it break any false belief, or assume the student already agrees?
+- Climax: is there a moment the whole thing builds to (a Big Domino), or does it just end?
+- Close: does it future-pace a payoff, or summarize?
+```
+
+```text
+Bad  (topic stack)  — "Agenda -> definition -> definition -> definition -> Q&A."
+Good (belief arc)   — "A 4am failure (hook) -> why retries scared us (false belief) -> the elevator-
+                       button realization (epiphany) -> retry fearlessly (Big Domino) -> what you'll
+                       do next incident (future-pace)."
+```
+
+Write the extracted spine into `02-DOCS/wiki/stack/course-storytelling.md` so the rework is diffable against the original.
+
+---
+
+## Step 4 — The gap map
+
+Per concept, flag what's missing. These flags are the work list and mirror exactly what `scripts/verify.sh` greps for.
+
+| Flag | Meaning | Fix (where) |
+| --- | --- | --- |
+| `no-story` | concept stated as fact, no epiphany | `brunson-frameworks.md` (Epiphany Bridge) |
+| `unnamed` | no sticky, ownable handle | `mental-models.md` (naming) |
+| `no-analogy` | abstract, nothing concrete | `mental-models.md` (analogy engineering) |
+| `jargon-dense` | unglossed terms stacked | `mental-models.md` (grounding) |
+| `no-application` | no do-this-now step | `concept-landing-recipe.md` (application beat) |
+| `no-so-what` | no future-paced payoff | `concept-landing-recipe.md` (so-what beat) |
+| `belief-not-broken` | teaches on top of a live false belief | `brunson-frameworks.md` (three beliefs) |
+
+```text
+GAP MAP (one row per concept)
+concept            | story | named | analogy | jargon | applic. | so-what | belief targeted
+-------------------+-------+-------+---------+--------+---------+---------+----------------------
+idempotency        | no    | no    | no      | HIGH   | no      | no      | (none) -> internal
+retry w/ backoff   | part  | no    | weak    | MED    | yes     | no      | vehicle
+circuit breaker    | no    | no    | no      | HIGH   | no      | no      | external
+```
+
+The map turns "this lesson is flat" into a concrete, finishable task list. Every flagged cell becomes a beat to write.
+
+---
+
+## Step 5 — Sequence for belief-building
+
+A topic list orders concepts by logical dependency. A *belief-building* spine orders them by what the student must come to believe, in what order, to topple the Big Domino. Resequence with these moves:
+
+1. **Set the Big Domino** for the module (→ `brunson-frameworks.md`). Every concept is either the story that knocks it over or a consequence that falls after.
+2. **Open on the wall, not the agenda.** Lead with the felt pain (the hook + the false belief), not a definition or a table of contents.
+3. **Break belief before building skill.** Put the belief-breaking epiphany *before* the mechanics of each concept, not after.
+4. **Order by emotional dependency, then logical.** Sometimes the logically-second concept should come first because it breaks the belief that unlocks the first. Story order ≠ dependency order.
+5. **Stack toward the domino.** Each concept should make the Big Domino more inevitable, so by the climax the student believes it almost before you say it.
+6. **Close on the future-paced payoff**, not a recap. Leave them seeing themselves using it.
+
+```text
+Bad  (dependency order)  — idempotency -> backoff -> circuit breaker (correct but flat)
+Good (belief order)      — the 4am double-charge (hook+pain) -> "retries are dangerous" (false
+                            belief) -> idempotency breaks it (epiphany+Big Domino: 'retry
+                            fearlessly') -> backoff and circuit breakers now land as obvious
+                            consequences -> "next incident you'll..." (future-pace)
+```
+
+### Output: the reworked narrative spine
+
+Produce a one-page spine for the module: the Big Domino, the opening hook, the ordered concept arc (with the false belief each one breaks), and the closing future-pace. Each concept in the arc then gets its full seven-beat treatment via `concept-landing-recipe.md`.
+
+## See Also
+
+- `../SKILL.md` — step 2 of the workflow invokes this analysis pass.
+- `brunson-frameworks.md` — the Big Domino and false-belief work the sequencing is built on.
+- `concept-landing-recipe.md` — each concept in the resequenced spine gets the seven-beat recipe.
+- `mental-models.md` — fixes for the `unnamed` / `no-analogy` / `jargon-dense` flags.
+- `learner-grounding.md` — the "do after" + transformation the inventory and spine are checked against.