@damiangilgonzalez/harness 1.3.7

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 (`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 `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 `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 `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 `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.

package/skills/course-storytelling/references/learner-grounding.md

@@ -0,0 +1,203 @@
+# Learner Grounding — Checklist, Question Script & Persistence
+
+The learner + audience profile is the source of truth every reframing is grounded in. You cannot make teaching *land* for a student you haven't profiled — you'll default to the AI-median explainer: abstract, jargon-true, emotionally dead. This file holds the **completeness checklist** (what "complete" means), the **question script** (how to interview the user, batched), and the **persistence format** (how to write it into `docs` and link it from `CLAUDE.md`). The runtime hard STOP that invokes this lives in `SKILL.md` under "Learner grounding (read this first)".
+
+## Where the profile lives
+
+Following the `harness` Karpathy-wiki convention:
+
+```text
+docs/
+├── raw/teaching/        ← immutable: transcripts, outlines, existing slides, pasted verbatim
+│   ├── transcript-module-1.md
+│   ├── outline.md
+│   └── …
+└── wiki/teaching/       ← compiled profile, one article per dimension
+    ├── index.md             ← the transformation one-liner + links to every dimension article
+    ├── learner.md           ← level, prior knowledge, pains, desires, what they want to DO after
+    ├── audience.md          ← buyer vs learner? live vs recorded? size? context?
+    ├── transformation.md    ← the one result; before → after
+    ├── false-beliefs.md     ← current false beliefs, typed vehicle / internal / external
+    └── constraints.md       ← format, length, medium, tone, hard limits
+```
+
+Small projects may collapse this into a single `index.md` with all dimensions as `##` headings — but every dimension must still be present and filled.
+
+## Completeness checklist
+
+The profile is **COMPLETE** only when every dimension is filled with real, specific content. Any empty, placeholder, or "TBD" dimension = **INCOMPLETE** = hard STOP, interview the user.
+
+- [ ] **1. Learner — level & prior knowledge** — who exactly is learning (role, experience), what they already know about this subject, what they definitely don't.
+- [ ] **2. Learner — pains & desires** — in THEIR words: the top 2–3 frustrations/fears around this topic, and the top 2–3 things they actually want.
+- [ ] **3. Learner — current false beliefs** — what they wrongly believe today that blocks the teaching, each typed as **vehicle** ("this approach won't work"), **internal** ("I can't do it"), or **external** ("something outside me will stop it"). (→ `brunson-frameworks.md`)
+- [ ] **4. Learner — the "do" after** — the concrete action/capability they should be able to perform after the lesson/module ("after this they can add an idempotency key to a POST and explain why").
+- [ ] **5. Audience — who's listening** — are the listeners the same as the buyer (decision-maker) or different? Live or recorded? Solo or cohort (size)? In what context do they consume it (commute, classroom, on the job)?
+- [ ] **6. Transformation — the one result** — the single before→after the whole course/module exists to produce, stated as an identity + capability shift, not a topic list.
+- [ ] **7. Constraints & format** — medium (video / live / written / slides), length budget, tone/voice expectations, hard limits (no code? must be language-agnostic? compliance constraints?).
+
+## Question script (ask in batches, never all at once)
+
+Ask **one batch at a time**. Send the batch, wait for the answer, persist what you learned, then send the next batch. Skip questions a located-but-incomplete profile already answers — only fill the gaps. Stop interviewing the moment all seven dimensions are complete.
+
+### Batch 1 — the learner
+
+```text
+1. Who is this for, exactly? Role, experience level, and how familiar they already are with the topic.
+2. What do they ALREADY know coming in, and what do they definitely NOT know yet?
+3. In THEIR words, what frustrates or scares them about this topic? (top 2–3)
+4. What do they actually want — the outcome that made them show up? (top 2–3)
+```
+
+### Batch 2 — false beliefs (the block)
+
+```text
+5. What do they wrongly BELIEVE about this topic today that gets in the way? For each, tell me
+   whether it's: "this approach won't work" (vehicle), "I personally can't do it" (internal),
+   or "something outside me will stop me" (external). I'll break each one with a story before teaching.
+6. After this lesson/module, what should they be able to DO that they couldn't before? (be concrete)
+```
+
+### Batch 3 — the audience & the medium
+
+```text
+7. Are the listeners the same people as the buyer/decision-maker, or different?
+8. Is this live or recorded? Solo learner or a cohort — roughly how many?
+9. Where/how do they consume it (on a commute, in a classroom, at their desk while working)?
+```
+
+### Batch 4 — transformation & constraints
+
+```text
+10. In one sentence: what's the single before→after this whole thing exists to produce? Frame it as
+    who they become + what they can now do, not a list of topics.
+11. What's the format and length budget? (video, live, written, slides; minutes/pages)
+12. Any hard constraints on tone, vocabulary, or content? (must be language-agnostic? no jargon?
+    compliance limits? a voice to match?)
+```
+
+If the user can't answer a question, that dimension stays incomplete — note the gap, keep the STOP in place for that dimension, and offer to draft a hypothesis they can confirm rather than fabricating an answer.
+
+## Persistence format
+
+### Profile wiki article template
+
+Each `docs/wiki/teaching/*.md` article follows the harness wiki format. It is an OKF v0.1 article: open it with YAML frontmatter carrying a non-empty `type:` (`teaching-profile`), then the H1 and body:
+
+```markdown
+---
+type: teaching-profile
+title: Teaching — Learner
+description: Who is learning, their level and prior knowledge, their pains and desires, and what they can DO after.
+tags: [teaching, learner, profile]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: teaching
+status: stable
+---
+
+# Teaching — Learner
+
+> Sources: {user interview, YYYY-MM-DD}
+> Raw: [transcript-module-1](../../raw/teaching/transcript-module-1.md)
+
+## Overview
+
+One paragraph: who is learning and what must change in them.
+
+## Level & prior knowledge
+
+- Role / experience: …
+- Already knows: …
+- Does not know yet: …
+
+## Pains & desires (their words)
+
+- Pain: …
+- Desire: …
+
+## The "do" after
+
+After this, the learner can: …
+
+## See Also
+
+- [Transformation](transformation.md)
+- [False beliefs](false-beliefs.md)
+```
+
+### False-beliefs article specifics
+
+`false-beliefs.md` must type every belief so `brunson-frameworks.md` can match it to a breaking story (same OKF frontmatter; `type: teaching-profile`):
+
+```markdown
+---
+type: teaching-profile
+title: Teaching — False Beliefs
+description: The learner's blocking beliefs, typed vehicle / internal / external, each with a breaking story.
+tags: [teaching, false-beliefs, profile]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: teaching
+status: stable
+---
+
+# Teaching — False Beliefs
+
+> Sources: {user interview, YYYY-MM-DD}
+
+## Vehicle ("this approach won't work")
+
+- "Tests just slow me down and don't catch real bugs." -> break with: the data-loss bug a
+  test-first caught when review missed it.
+
+## Internal ("I can't do it")
+
+- "TDD is for real engineers, I just hack." -> break with: your year-one CRUD feature where
+  test-first made you faster.
+
+## External ("something outside me will stop it")
+
+- "My deadline won't allow tests first." -> break with: the sprint where the test became the
+  spec and shipped early.
+```
+
+### Raw inputs
+
+Paste each user-provided transcript / outline / slide deck verbatim into its own `docs/raw/teaching/<name>.md` with a one-line provenance header:
+
+```markdown
+> Source: user-pasted, YYYY-MM-DD, origin: "Module 1 lecture transcript"
+
+<the material, unedited>
+```
+
+### CLAUDE.md link
+
+Add (or update) this section in the root `CLAUDE.md`. Additive only — never delete existing sections. Create `CLAUDE.md` if absent.
+
+```markdown
+## Knowledge map
+
+Teaching is grounded in the learner + audience profile under `docs/wiki/teaching/`.
+Read it before reframing any lesson:
+
+- [Transformation (index)](docs/wiki/teaching/index.md)
+- [Learner](docs/wiki/teaching/learner.md)
+- [Audience](docs/wiki/teaching/audience.md)
+- [Transformation](docs/wiki/teaching/transformation.md)
+- [False beliefs](docs/wiki/teaching/false-beliefs.md)
+- [Constraints & format](docs/wiki/teaching/constraints.md)
+
+Course teaching conventions (narrative spine, named models, Big Dominoes, Attractive Character):
+`docs/wiki/stack/course-storytelling.md`.
+Raw transcripts / outlines / slides: `docs/raw/teaching/`.
+The `course-storytelling` skill maintains this profile and stops to interview the user
+if any dimension is missing.
+```
+
+If a `## Knowledge map` section already exists (e.g. from `marketing`/`design`), append the teaching links to it rather than creating a second one.
+
+## See Also
+
+- `../SKILL.md` — the runtime grounding mechanism (hard STOP) that uses this checklist.
+- `brunson-frameworks.md` — consumes the typed false beliefs and the transformation.
+- `course-analysis.md` — uses the "do after" + transformation to sequence the spine.
+- `../../harness/SKILL.md` — the canonical `docs` wiki protocol and article templates.