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 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)"

# 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.

# 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.

# 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.

# 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.

# 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 `02-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
02-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 `02-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 `02-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 `02-DOCS/wiki/teaching/`.
Read it before reframing any lesson:

- [Transformation (index)](02-DOCS/wiki/teaching/index.md)
- [Learner](02-DOCS/wiki/teaching/learner.md)
- [Audience](02-DOCS/wiki/teaching/audience.md)
- [Transformation](02-DOCS/wiki/teaching/transformation.md)
- [False beliefs](02-DOCS/wiki/teaching/false-beliefs.md)
- [Constraints & format](02-DOCS/wiki/teaching/constraints.md)

Course teaching conventions (narrative spine, named models, Big Dominoes, Attractive Character):
`02-DOCS/wiki/stack/course-storytelling.md`.
Raw transcripts / outlines / slides: `02-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 `02-DOCS` wiki protocol and article templates.

# Mental Models — Naming, Analogy Engineering & Grounding

A concept the student can't *name* is a concept they can't repeat — and what can't be repeated isn't retained. A concept they can't picture is one that never gets concrete enough to *use*. This file is the craft of both: designing sticky, ownable names and engineering the analogies that drop an abstraction down to earth. It feeds the "MENTAL MODEL" and "GROUNDED ANALOGY" beats of the landing recipe (`concept-landing-recipe.md`) and the "new opportunity" handoff from `brunson-frameworks.md`.

---

## Part 1 — Designing a named mental model

A mental model is a short, ownable handle the student carries out of the lesson and reuses. Good names do three jobs: **compress** (one phrase recalls the whole idea), **transfer** (it applies beyond the example), and **stick** (it's easy to say and hard to forget).

### The naming tests (a name must pass all four)

1. **Sayable** — a student can repeat it out loud, from memory, a week later. 2–4 words.
2. **Picturable** — it evokes a concrete image or object, not an abstraction. ("The Elevator Button" pictures; "Operational Convergence" does not.)
3. **Ownable** — it's specific enough to feel like *this* teacher's coinage, not a generic term they could Google.
4. **Load-bearing** — the name encodes the *mechanism*, so recalling the name recalls how it works.

### Naming patterns that work

| Pattern | Shape | Example (for a concept) |
| --- | --- | --- |
| Concrete object | "The [familiar object]" | "The Elevator Button" (idempotency) |
| Vivid action | "[Verb] the [noun]" | "Shrink the Blast Radius" (fault isolation) |
| Memorable contrast | "[X], not [Y]" | "Spec, Not Chore" (test-first) |
| Rule of N | "The [N] [things]" | "The Two-Pizza Rule" (team size) |
| Named law/effect | "The [Name] [Law/Effect]" | "The Last-Mile Tax" (deployment friction) |

```text
Bad  (no name)    — "We should design operations so repeated execution is safe."
Bad  (jargon name)— "Operational Idempotence Convergence" (unsayable, unpicturable, un-ownable)
Good (named)      — "The Elevator Button: press it five times, one elevator still comes."
```

### Where names live

Persist every coined model in `02-DOCS/wiki/stack/course-storytelling.md` (or under `wiki/teaching/`) so names stay consistent across lessons and the student hears the same handle every time. A model renamed mid-course is a model un-learned.

---

## Part 2 — Analogy & metaphor engineering

An analogy maps an unfamiliar concept onto something the student already understands deeply. Engineered well, it does the explaining for you. Engineered carelessly, it teaches the wrong thing.

### The mapping method

```text
ANALOGY MAP
Target (unfamiliar) ... the concept you're teaching
Source (familiar) ..... something from the LEARNER'S world (from wiki/teaching/learner.md)
Mapped parts .......... list each piece of the target -> its match in the source
Where it breaks ....... the ONE place the analogy fails (state it — prevents over-extension)
```

### Rules

- **Source from THEIR world, not yours.** A cooking analogy for chefs, a sports analogy for athletes, a spreadsheet analogy for finance folks. Pull the source domain from the learner profile.
- **Map the mechanism, not just the vibe.** A good analogy survives "okay, so what happens when…" — the parts correspond. A vibe-only analogy ("it's like magic") collapses on the first follow-up.
- **State where it breaks.** Every analogy fails somewhere. Naming the break point *before* a student finds it keeps trust and prevents them from learning the wrong thing.
- **One analogy per concept.** Stacking three analogies for one idea dilutes all three. Pick the strongest.

### Worked example — "idempotency" → "The Elevator Button"

```text
Target: an idempotent operation (repeated calls = one effect)
Source: pressing an elevator call button
Mapped parts:
  - the request          -> pressing the button
  - the side effect      -> one elevator dispatched
  - retries / dup sends  -> pressing the lit button again
  - the idempotency key  -> the button's "already lit" state
Where it breaks: a real elevator eventually arrives regardless; an idempotent API needs the key
  to RECOGNIZE the duplicate — name this so they don't think "it just works by magic".
```

```text
Bad  (vibe only)  — "Idempotency is like, you know, it just handles duplicates gracefully."
Good (mapped)     — the elevator map above: every part corresponds, and the break is named.
```

---

## Part 3 — Grounding abstract → concrete

Three moves that pull an abstraction down to where the student lives.

1. **Replace the variable with a value.** Don't say "for any request"; say "for *your* 4pm deploy." Specifics are graspable; generalities float.
2. **Explain it like their day.** Recast the concept inside a moment from the learner's actual routine (commute, standup, the ticket they're avoiding). Pulled from `wiki/teaching/learner.md`.
3. **Future-pace it.** Walk them through a near-future moment where they use the idea and it pays off. The brain pre-experiences the win and wants the concept that delivers it. (Story-selling move — see `brunson-frameworks.md`.)

```text
Bad  (abstract)  — "Backoff prevents thundering-herd retries from overwhelming a recovering service."
Good (grounded)  — "Your service just came back from an outage. The instant it's up, 10,000 queued
                    retries hit it at once and knock it over again. Backoff is everyone waiting a
                    polite, increasing beat before knocking — so the recovering service can breathe.
                    Next incident, you'll add jittered backoff and watch the recovery actually hold."
```

---

## Part 4 — "Make it land" tests

Apply these to any reframed concept before shipping. If it fails one, it isn't landed.

- **The repeat-back test.** Could the student explain this to a peer in one sentence using your name for it? If not, the name or analogy is weak.
- **The week-later test.** Will they still recall the name and the picture next week with no notes? If it needs notes, it's not sticky.
- **The follow-up test.** Does the analogy survive "okay, but what about…"? If it collapses, the mapping is vibe-only — re-map or name the break.
- **The so-what test.** Can the student say why it matters to *them*, in their world? If not, you stopped before grounding.
- **The jargon test.** Every term either glossed, grounded, or cut. An unexplained term is a leak where attention drains out.

## See Also

- `../SKILL.md` — the non-negotiables (name everything, ground everything).
- `concept-landing-recipe.md` — where the named model + analogy slot into the seven beats.
- `brunson-frameworks.md` — the "new opportunity" beat that hands off to the named model; future-pacing.
- `learner-grounding.md` — the learner's world that analogy source domains are drawn from.

#!/usr/bin/env bash
#
# verify.sh — "did it land?" QA gate for the `course-storytelling` skill.
#
# WHAT IT DOES (read-only; never edits a file)
#   Static, network-free heuristics over your lesson/course source files. For each
#   concept section it checks that the teaching has the ingredients that make it land:
#     1. Story presence    — a section that teaches a concept but has no narrative
#        markers (no "I", no "story", no time/place setup) is a `no-story` lesson.
#     2. Named model       — a memorable, ownable name (a "The X" handle / bolded coinage).
#     3. Grounded analogy  — an analogy marker ("like", "imagine", "think of it as").
#     4. Application step   — a do-this-now action ("try this", "do this", "your turn").
#     5. So-what payoff     — a future-paced close ("next time", "you'll be able to", "so that").
#     6. Abstraction / jargon density — flags sections heavy on abstract nouns
#        (-tion/-ity/-ность style) with no analogy nearby.
#     7. markdownlint of lesson sources, if markdownlint is installed.
#
#   Every finding is a WARNING by default (teaching is judgement, not pass/fail).
#   Use --strict to turn warnings 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 lesson sources (*.md, *.mdx, *.txt)
#   ./verify.sh --path lessons  # 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..44), stripping the leading "# "
  sed -n '2,44p' "$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.
# Robust across BSD/GNU: wc -l can print leading spaces, so strip non-digits.
count_lines() {
  if [ -s "$1" ]; then
    wc -l < "$1" 2>/dev/null | tr -dc '0-9'
  else
    printf '0'
  fi
}

# find lesson source files (markdown / text). Prints one path per line.
# Excludes the conventional 02-DOCS wiki/raw so we lint LESSONS, not the profile.
list_lessons() {
  find "$SCAN_PATH" \
    \( -name '*.md' -o -name '*.mdx' -o -name '*.txt' \) \
    -type f \
    ! -path '*/node_modules/*' \
    ! -path '*/.git/*' \
    ! -path '*/02-DOCS/*' \
    2>/dev/null || true
}

# file_has <file> <pattern>: 0 if the (case-insensitive) pattern appears in the file.
file_has() { grep -iqE "$2" "$1" 2>/dev/null; }

# --- ensure we have a searcher ----------------------------------------------
# The per-file checks use grep (via file_has); find gathers the lesson list.
if ! have grep; then
  skip "grep not found — cannot scan lesson 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 lesson files ----------------------------------------------------
TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/verify-cs.%s' "$$")"
mkdir -p "$TMPDIR_V" 2>/dev/null || true
cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
trap cleanup EXIT

LESSONS="$TMPDIR_V/lessons"
list_lessons > "$LESSONS" 2>/dev/null || true
n_lessons="$(count_lines "$LESSONS")"

if [ "$n_lessons" -eq 0 ]; then
  skip "no lesson 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 lesson file(s) under: %s\n\n' "$n_lessons" "$SCAN_PATH"

# Heuristic markers (case-insensitive ERE).
STORY_RE='\bi (was|had|remember|learned|realized|once)\b|\bstory\b|\bone (day|night|morning)\b|at the time|years? (ago|in)|epiphany|the moment (i|we|they)'
NAME_RE='\bthe [A-Z][a-z]+( [A-Z][a-z]+)?\b|\*\*[^*]+\*\*|call (it|this) the|i call (it|this)|known as the'
ANALOGY_RE='\blike (a|an|the|your)\b|\bimagine\b|\bthink of (it|this) as\b|\bit.?s (basically|essentially) (a|an|like)\b|analog|metaphor|as if'
APPLICATION_RE='\btry (this|it)\b|\bdo this\b|\byour turn\b|right now|before you (close|move|continue)|exercise|step 1|hands.?on|go (build|add|write|open)'
SOWHAT_RE='next time|you.?ll (be able|now|never)|so that you|what.?s now possible|from now on|imagine being able|future|the payoff'

# Per-file results (bash 3.2: append to temp files, count in parent shell).
NS="$TMPDIR_V/no_story";   : > "$NS"
NN="$TMPDIR_V/no_name";    : > "$NN"
NA="$TMPDIR_V/no_analogy"; : > "$NA"
NP="$TMPDIR_V/no_appl";    : > "$NP"
NW="$TMPDIR_V/no_sowhat";  : > "$NW"

while IFS= read -r f; do
  [ -z "$f" ] && continue
  file_has "$f" "$STORY_RE"       || printf '%s\n' "$f" >> "$NS"
  file_has "$f" "$NAME_RE"        || printf '%s\n' "$f" >> "$NN"
  file_has "$f" "$ANALOGY_RE"     || printf '%s\n' "$f" >> "$NA"
  file_has "$f" "$APPLICATION_RE" || printf '%s\n' "$f" >> "$NP"
  file_has "$f" "$SOWHAT_RE"      || printf '%s\n' "$f" >> "$NW"
done < "$LESSONS" || true   # read returns 1 at EOF; harmless under set -e

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/^/        /'
    warn_count=$((warn_count + n - 1))   # warn() already counted 1
  else
    ok "no $label"
  fi
}

# --- 1..5 landing-ingredient checks -----------------------------------------
report_files "lessons with no story marker (add an Epiphany Bridge beat)"        "$NS"
report_files "lessons with no named mental model (name the concept)"             "$NN"
report_files "lessons with no grounded analogy (add a concrete metaphor)"        "$NA"
report_files "lessons with no application step (add a do-this-now)"              "$NP"
report_files "lessons with no so-what payoff (future-pace the close)"            "$NW"

# --- 6. abstraction / jargon density ----------------------------------------
# Heuristic: lines dense in abstract -tion/-ity/-ism nouns. Flag files where such
# lines appear AND the file has no analogy marker (analogy is the antidote).
ABSTRACT_RE='\b[a-z]{4,}(tion|ality|ility|ism|ance|ence)\b'
JARGON_HITS="$TMPDIR_V/jargon"; : > "$JARGON_HITS"
while IFS= read -r f; do
  [ -z "$f" ] && continue
  dense="$(grep -ioE "$ABSTRACT_RE" "$f" 2>/dev/null | wc -l | tr -dc '0-9')"
  [ -z "$dense" ] && dense=0
  if [ "$dense" -ge 12 ] && ! file_has "$f" "$ANALOGY_RE"; then
    printf '%s (%s abstract nouns, no analogy)\n' "$f" "$dense" >> "$JARGON_HITS"
  fi
done < "$LESSONS" || true   # read returns 1 at EOF; harmless under set -e
n_jargon="$(count_lines "$JARGON_HITS")"
if [ "$n_jargon" -gt 0 ]; then
  warn "jargon/abstraction-dense lessons with no grounding analogy ($n_jargon file(s)):"
  head -n 8 "$JARGON_HITS" | sed 's/^/        /'
  warn_count=$((warn_count + n_jargon - 1))
else
  ok "no abstraction-dense, analogy-less lessons"
fi

# --- 7. markdownlint of lesson sources (if available) -----------------------
if have markdownlint; then
  # Lint only the lesson files; warn on findings, never fail the gate here.
  ml_out="$TMPDIR_V/mdlint"
  # shellcheck disable=SC2046  # word-splitting the file list is intended here
  markdownlint $(cat "$LESSONS") > "$ml_out" 2>&1 || true
  if [ -s "$ml_out" ]; then
    warn "markdownlint findings in lesson sources:"
    head -n 10 "$ml_out" | sed 's/^/        /'
  else
    ok "markdownlint clean on lesson 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 — teaching is judgement, not pass/fail.
Review each: does the concept actually have a story, a named model, a grounded analogy, an
application step, and a so-what? Then fix or justify. 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