@ericrisco/rsc 0.1.44 → 0.1.46

package/skills/cost-tracking/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cost-tracking
-description: "Use when you need to track and cap what an AI or cloud app spends — capturing per-request tokens, pricing them against a current rate table, ledgering spend per user/feature/model/tenant, and firing budget alerts or a hard cap before the bill lands instead of after. Triggers: 'track token costs per request', 'cap our OpenAI/Claude spend', 'budget alert before we blow the bill', 'attribute cost per user or tenant', 'a runaway agent loop just burned $X', 'is prompt caching actually cheaper and where is the break-even', 'why is our bill 3x the estimate', 'reconcile billed usage against the response usage object', 'cuánto gastamos en tokens este mes', 'pon un tope de gasto a la API y avísame al 80%', 'controlar el cost de la IA'. NOT company cash runway or burn (that is finance-ops), NOT cost-per-unit margin (that is unit-economics), NOT the accounting record of the spend (that is bookkeeping)."
+description: "Use when metering and capping AI or cloud app spend — tokens read from the response `usage` object, priced off a dated rate table, ledgered per user/tenant/feature, with alerts and a hard cap before the bill. NOT cash runway (that is `finance-ops`), NOT cost-per-unit margin (that is `unit-economics`), NOT booking the spend (that is `bookkeeping`)."
 tags: ["cost-tracking", "token-accounting", "llm-spend", "budgets", "alerts", "prompt-caching", "billing-guardrails", "finops"]
 recommends: ["finance-ops", "unit-economics", "analytics", "stripe", "aws-essentials", "gcp-essentials"]
 origin: risco
@@ -110,7 +110,7 @@ CREATE TABLE llm_cost_ledger (
 );
 ```
 
-This is an *operational* ledger, not the accounting record — categorizing the spend into the books is `bookkeeping`.
+This is an *operational* ledger, not the accounting record — categorizing the spend into the books is `bookkeeping`, and the same rows feed the cost numerator in `unit-economics` and one input line in `finance-ops`. "Cost per active user" on the behavior side is `analytics`; charging customers for metered usage is `stripe`.
 
 ## Budgets, alerts, caps
 
@@ -144,7 +144,7 @@ App-level metering is your real-time guard. Cloud billing alerts are a **delayed
 - **AWS** Cost Anomaly Detection is ML-based, runs ~3x/day with up to 24h data delay → SNS → Lambda. AWS Budgets adds threshold alerts on the same pipe.
 - **GCP/Azure** are threshold-only. GCP's budget → Pub/Sub → Cloud Function is the one that can actually *pause or throttle* a workload programmatically.
 
-Route every cloud alert into the **same alert pipe** as your app-level budget alerts so there's one place to look. The 24h delay is exactly why the in-app cap exists: by the time AWS notices the anomaly, the loop already spent the money. Recipes and the alert-routing pattern are in `references/cloud-caps.md`.
+Route every cloud alert into the **same alert pipe** as your app-level budget alerts so there's one place to look. The 24h delay is exactly why the in-app cap exists: by the time AWS notices the anomaly, the loop already spent the money. Recipes and the alert-routing pattern are in `references/cloud-caps.md`; the cap plumbing in depth is `aws-essentials` / `gcp-essentials`.
 
 ## Build vs buy
 
@@ -173,11 +173,3 @@ Route every cloud alert into the **same alert pipe** as your app-level budget al
 ## Verify the artifact
 
 `scripts/verify.sh [path]` lints a candidate cost config/ledger (yaml/json/ts) and fails if: a pricing entry lacks `effective_date` or `source`; a model referenced in logic is missing from the table; the ledger schema lacks an idempotency/request key or any attribution key; the budget declares no soft+hard pair; or cost looks derived from a `len()`/char estimate instead of a `usage` field. It is read-only and exits 0 on a clean config and on no config found — no false failure.
-
-## Where this hands off
-
-- Company cash runway / burn / forecast → `finance-ops` (cost-tracking is one input line).
-- Cost-per-unit margin, contribution, CAC:LTV → `unit-economics` (this produces the cost numerator).
-- "Cost per active user" behavior side / product telemetry → `analytics`.
-- Billing customers, metered usage charges → `stripe`.
-- The AWS/GCP cap plumbing in depth → `aws-essentials` / `gcp-essentials`.

package/skills/course-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: course-builder
-description: "Use when you must turn a vague \"I want to teach X\" into a defensible course/curriculum skeleton — writing measurable learning outcomes, designing assessment that proves them, sequencing modules, scoping a workshop/bootcamp/cohort/onboarding track, or building an outcome×module×assessment alignment matrix. Triggers: 'structure my course', 'turn these topics into a curriculum', 'write learning outcomes / objectives', 'design the final project and quizzes', 'map my modules to outcomes', 'is my course actually aligned?', 'my course just ends with no real endpoint — what should they be able to DO?', 'estructura el temario de mi curso', 'define los resultados de aprendizaje', 'dissenya el pla docent', 'quina avaluació demostra cada objectiu'. NOT making a concept land emotionally (that is course-storytelling)."
+description: "Use when turning \"I want to teach X\" into a defensible course skeleton — measurable outcomes (Bloom + ABCD), assessment that proves each one, sequenced modules, and an outcome×module×assessment matrix — for a workshop, bootcamp, cohort or onboarding track. NOT making one concept land emotionally with story or analogy (that is course-storytelling)."
 tags: [course, curriculum, instructional-design, learning-outcomes, assessment]
 recommends: [course-storytelling, presentations, sop-builder]
 origin: risco
@@ -12,21 +12,10 @@ origin: risco
 
 This skill owns the **skeleton**: the measurable outcomes, the assessment that certifies each one, the module sequence that builds toward them, and the alignment matrix tying it all together. It does not own the *teaching* of any one concept.
 
-## What this skill owns / does NOT own
-
-**Owns:** desired results (outcomes), acceptable evidence (assessment), build order (module sequence), and the outcome×module×assessment matrix that proves nothing is orphaned or unproven.
-
-**Does NOT own:**
-
-- Making a single concept *click and stick* emotionally — epiphany, sticky names, grounded analogies. That is `../course-storytelling/SKILL.md`. Build the skeleton HERE first, then hand each module there to make it land.
-- Auditing a *finished* course for gaps, redundancy, anachronisms with a written report → `../review/SKILL.md`.
-- Turning a designed module into slides/decks → `../presentations/SKILL.md` (+ `../design/SKILL.md` for the visual system).
-- Sales/landing copy and launch emails → `../marketing/SKILL.md`. You design the learning contract, never the pitch.
-- Fact-checking or sourcing the subject matter → `../research-ops/SKILL.md`. You structure what the user already knows.
-- A repeatable internal procedure with steps but no outcomes/assessment → `../sop-builder/SKILL.md`. An SOP tells someone the steps; a course changes what they can DO and proves it.
-
 **The litmus.** If the question is *"what must the learner be able to DO, how do we prove it, and in what order do we build it?"* → here. If it's *"how do I make THIS concept click and stick?"* → `../course-storytelling/SKILL.md`.
 
+Route elsewhere when: auditing a *finished* course for gaps, redundancy, anachronisms with a written report → `../review/SKILL.md`; turning a designed module into slides/decks → `../presentations/SKILL.md` (+ `../design/SKILL.md` for the visual system); sales/landing copy and launch emails → `../marketing/SKILL.md` (you design the learning contract, never the pitch); fact-checking or sourcing the subject matter → `../research-ops/SKILL.md` (you structure what the user already knows); a repeatable internal procedure with steps but no outcomes/assessment → `../sop-builder/SKILL.md` (an SOP tells someone the steps; a course changes what they can DO and proves it).
+
 ## The grounding gate (read first — STOP if unmet)
 
 You cannot design a course backward without knowing the destination. Do not write a single outcome until you have all three. Why: an outcome scoped for a senior engineer in a 90-minute workshop is wrong for a beginner in a 12-week cohort — same topic, different contract.
@@ -37,24 +26,9 @@ You cannot design a course backward without knowing the destination. Do not writ
 
 If a `02-DOCS/wiki/teaching/` profile exists (the convention shared with `../course-storytelling/SKILL.md`), read it first and reuse it. Otherwise interview in ONE batch — ask all three at once, do not dribble questions. **Incomplete grounding = STOP and ask.** Depth, the interview script, and scope right-sizing by format → `references/grounding-and-scoping.md`.
 
-## The non-negotiables
-
-Each rule carries its one-line reason. Break one and the skeleton is not defensible.
-
-1. **Design backward: outcomes first, then assessment, then content.** UbD has exactly three stages in order — desired results → acceptable evidence → learning experiences (Wiggins & McTighe, *Understanding by Design*). Content designed first is a dump with no destination.
-2. **Every outcome uses a measurable Bloom verb.** The revised taxonomy (Anderson & Krathwohl, 2001) is six ascending levels of *verbs* — Remember → Understand → Apply → Analyze → Evaluate → Create — each supplying observable action verbs. A verb you can't observe, you can't assess.
-3. **Banlist: never "understand", "know", "learn about", "appreciate", "be aware", "be familiar".** They name a private mental state, not an observable behavior. Replace with what the learner *does*: list, explain, build, debug, evaluate, design.
-4. **Each outcome is ABCD-complete.** Audience + Behavior (verb + object) + Condition (situation/tools) + Degree (success criterion). A bare verb without a condition and a degree is not yet assessable — "write code" vs "given a failing test, write code that makes it pass".
-5. **Every outcome is proven by ≥1 assessment.** No unproven outcomes. An outcome with no evidence is a promise you never keep.
-6. **Every module ties to ≥1 outcome.** No orphan modules. If a module maps to no outcome, it's content the contract never asked for — cut it or write the outcome it serves.
-7. **The verb in the outcome = the verb activated in teaching = the verb verified in assessment** (constructive alignment, Biggs). If the outcome says "design" and the quiz tests "recall", the assessment proves the wrong thing.
-8. **Place BOTH formative and summative assessment.** Formative runs *during* learning (low/no stakes — quizzes, checklists, drafts) to give feedback; summative runs *at the end* (the project, the exam) to certify mastery. A course with only the final exam gives the learner no feedback loop.
-9. **No content-first design.** "I already have these slides, build a course around them" inverts the contract. Outcomes decide what content survives.
-10. **Right-size scope to format.** A 90-minute workshop earns ~1–2 outcomes; a 12-week cohort earns 5–8. Cramming a bootcamp's outcomes into a workshop guarantees none are actually achieved.
-
 ## The build workflow (one backward pass)
 
-Run it in order. Do not jump to modules.
+Run it in order. Do not jump to modules. UbD has exactly three stages in order — desired results → acceptable evidence → learning experiences (Wiggins & McTighe, *Understanding by Design*). Content designed first is a dump with no destination, and "I already have these slides, build a course around them" inverts the contract: outcomes decide what content survives.
 
 ```text
 Stage 0  Grounding gate         WHO + WHAT transformation + FORMAT. Incomplete → STOP.
@@ -70,9 +44,9 @@ Stage 5  QA gate                Run scripts/verify.sh over the curriculum doc. F
                                 or justify them. Then hand modules to course-storytelling.
 ```
 
-## Writing measurable outcomes
+## Stage 1 — Writing measurable outcomes
 
-Pick the verb at the level the learner must actually operate. Recall ≠ build.
+Pick the verb at the level the learner must actually operate. Recall ≠ build. The revised taxonomy (Anderson & Krathwohl, 2001) is six ascending levels of *verbs*, each supplying observable action verbs — a verb you can't observe, you can't assess.
 
 ```text
 Level         What the learner does          Sample verbs
@@ -84,7 +58,9 @@ Evaluate      judge against criteria         evaluate, critique, justify, priori
 Create        produce something new          design, build, compose, construct, ship
 ```
 
-The **ABCD template** for one outcome:
+**Banlist — never "understand", "know", "learn about", "appreciate", "be aware", "be familiar".** They name a private mental state, not an observable behavior. Replace with what the learner *does*: list, explain, build, debug, evaluate, design.
+
+Every outcome is **ABCD-complete** — a bare verb without a condition and a degree is not yet assessable ("write code" vs "given a failing test, write code that makes it pass"):
 
 ```text
 [Audience]   the learner
@@ -111,9 +87,9 @@ Good: Given a 20-line module, the learner writes 3 tests that cover the happy pa
 
 Full per-level verb tables, the banlist, more worked ABCD examples, and course-level vs module-level granularity → `references/outcomes-and-blooms.md`.
 
-## Designing aligned assessment
+## Stage 2 — Designing aligned assessment
 
-Assessment is the proof, not an afterthought. For every outcome, ask: *what would I have to SEE the learner do to believe they achieved it?* — and make that the assessment.
+Assessment is the proof, not an afterthought. For every outcome, ask: *what would I have to SEE the learner do to believe they achieved it?* — and make that the assessment. Place **both** kinds: an outcome with no evidence is a promise you never keep, and a course with only the final exam gives the learner no feedback loop.
 
 ```text
                  Formative (during)              Summative (at the end)
@@ -127,12 +103,12 @@ Bloom fit        Remember/Understand/Apply        Apply/Analyze/Evaluate/Create
 
 Two hard checks:
 
-- **Verb match.** The assessment must require the *same* verb as the outcome. Outcome "build" → assessment is a build, not a multiple-choice quiz. Outcome "evaluate" → assessment asks for a judgement with justification, not recall.
+- **Verb match** (constructive alignment, Biggs). The assessment must require the *same* verb as the outcome. Outcome "build" → assessment is a build, not a multiple-choice quiz. Outcome "evaluate" → assessment asks for a judgement with justification, not recall. If the outcome says "design" and the quiz tests "recall", the assessment proves the wrong thing.
 - **Content validity.** The set of assessments must cover the *breadth* of the outcomes — every outcome touched, none over-weighted into a vanity exam. Competency-based design maps this via the matrix and certifies demonstrated mastery, not seat time.
 
 The full formative↔summative menu mapped to Bloom levels, the content-validity / blueprint checklist, and the verb-match rule worked end-to-end → `references/assessment-design.md`.
 
-## Sequencing modules + the alignment matrix
+## Stages 3–4 — Sequencing modules + the alignment matrix
 
 Order modules by **prerequisite** (you can't build before you can run), give each **one focus**, and map each to ≥1 outcome. Then emit the matrix — this is the artifact `scripts/verify.sh` checks.
 
@@ -144,7 +120,7 @@ Order modules by **prerequisite** (you can't build before you can run), give eac
 | O3 evaluate an API's error model | M5               | F: M5 peer review · S: capstone rubric|
 ```
 
-Read the matrix two ways: down a column finds **orphan modules** (a module in no row → cut or justify); across the outcome list finds **unproven outcomes** (an outcome with an empty assessment cell → design evidence). A complete matrix has no empty cells.
+Read the matrix two ways: down a column finds **orphan modules** (a module in no row → content the contract never asked for, so cut it or write the outcome it serves); across the outcome list finds **unproven outcomes** (an outcome with an empty assessment cell → design evidence). A complete matrix has no empty cells.
 
 ## Decision table (branch only where the flow actually splits)
 
@@ -175,12 +151,8 @@ Attitude/disposition outcome      Assess with reflection + observed behavior; ha
 | Summative-only: just a final exam | No feedback loop during learning | Place formative checkpoints throughout |
 | Scope creep: bootcamp outcomes in a workshop | None are actually achievable in the time | Right-size outcome count to the format |
 
-## Hand-off
-
-The skeleton is the start, not the finish.
+## Stage 5 — QA gate and hand-off
 
-- Skeleton + matrix pass QA → hand **each module** to `../course-storytelling/SKILL.md` to make the teaching land (epiphany, named models, grounded analogies). You built *what* and *in what order*; that skill makes it stick.
-- Need decks → `../presentations/SKILL.md` for slides, `../design/SKILL.md` for the visual system.
-- A repeatable team procedure surfaced that isn't a course → `../sop-builder/SKILL.md`.
+`scripts/verify.sh` checks your curriculum's STRUCTURE and ALIGNMENT (measurable verbs, the matrix, proven outcomes, formative + summative). Fix its warnings or justify them.
 
-The boundary is executable: `scripts/verify.sh` checks your curriculum's STRUCTURE and ALIGNMENT (measurable verbs, the matrix, proven outcomes, formative + summative). It does not judge whether the teaching lands — that is `course-storytelling`'s job, and its verify.sh checks narrative, not structure.
+Then hand **each module** to `../course-storytelling/SKILL.md` to make the teaching land (epiphany, named models, grounded analogies). You built *what* and *in what order*; that skill makes it stick. The boundary is executable: this skill's verify.sh does not judge whether the teaching lands, and `course-storytelling`'s checks narrative, not structure.

package/skills/course-storytelling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: course-storytelling
-description: "Use when you have course / lesson / module content and you need the teaching to LAND — so grounded, named, and emotionally resonant that the student loves the teacher. Ingests slides/transcripts/notes/outline, extracts the concepts AND the existing narrative spine, finds the abstract/jargon-heavy/ungrounded gaps, then reframes each concept with Russell Brunson's Expert Secrets methodology (Epiphany Bridge, the three false beliefs, the Big Domino, named mental models, story-selling, grounding analogies, future-pacing). Profiles the LEARNER and AUDIENCE first (hard gate). Outputs a per-concept 'landing recipe' and a reworked narrative spine. Triggers: 'make this lesson land', 'teach this concept', 'storytelling for my course', 'expert secrets', 'epiphany bridge', 'mental models for teaching', 'this lesson is too abstract', 'my students aren't getting it', 'name this concept'. NOT slide visuals (that's `presentations`/`design`) and NOT a content-audit/review pass (run review-content first, bring findings here)."
+description: "Use when lesson or course content is correct but forgettable and a concept has to LAND: profiles the learner, breaks the blocking false belief, then rebuilds it as epiphany story → named model → grounded analogy → proof → so-what. NOT outcomes, assessment or module order (that is `course-builder`), NOT slide visuals (that is `presentations`)."
 tags: [course, teaching, storytelling, content]
 recommends: [presentations]
 origin: risco
@@ -10,75 +10,38 @@ origin: risco
 
 *Take a concept the student would forget and turn it into one they can't unhear. Profile the learner first, then run every concept through the Expert Secrets machine: epiphany story → named model → grounded analogy → proof → do-this-now → the so-what.*
 
-This skill owns **the teaching narrative**: extracting what a course actually teaches, finding where it stays abstract, and rebuilding each concept so the realization happens *in the student*, emotionally, not just on the slide. It borrows Russell Brunson's *Expert Secrets* frameworks as a **teaching methodology** (this is method, not text reproduction). The sibling `presentations` skill turns the result into a deck; `marketing` owns sales words; `design` owns pixels; a content-audit/review-content pass audits an existing lesson for gaps before you bring it here.
+This skill owns **the teaching narrative**: extracting what a course actually teaches, finding where it stays abstract, and rebuilding each concept so the realization happens *in the student*, emotionally, not just on the slide. It borrows Russell Brunson's *Expert Secrets* frameworks as a **teaching methodology** (this is method, not text reproduction).
 
-## When to use / When NOT to use
-
-Use when:
-
-- You have lesson/module/course material (slides, transcript, notes, outline) and the teaching feels flat, abstract, or forgettable.
-- A concept is technically correct but "doesn't click" — students nod and forget.
-- You want a sticky, ownable name + a grounded analogy + a story for an idea.
-- You're sequencing a course and need a belief-building narrative spine, not just a topic list.
-- You want the student to *feel* the epiphany the expert felt, so they trust the teacher.
-
-Do NOT use when (delegate or decline):
-
-- Designing the slide visuals, layout, or exporting a deck → `presentations` (+ `design` for the visual system).
-- Writing sales/landing copy for the course → `marketing`.
-- Auditing an existing lesson for gaps/redundancy/anachronisms with a written report → a content-audit/review-content pass (run it first; bring its findings here).
-- Pure fact-checking or research of the subject matter → `deep-research`.
+Boundaries: `course-builder` decides what the course must prove — outcomes, assessment, module order — and hands you the skeleton; this skill makes each concept inside it land. `presentations` turns the landed lesson into a deck, `design` owns the pixels, `marketing` owns the words that sell the course, and a content-audit/review-content pass diagnoses an existing lesson (run it first, bring its findings here — that pass audits, this one rebuilds).
 
 **Teaching ≠ selling.** Brunson's frameworks here serve comprehension and retention. The "sale" you're closing is *belief in the idea and trust in the teacher* — never bolt a pitch onto a lesson.
 
-## Learner grounding (read this first)
-
-**Hard rule: never reframe or rewrite teaching without a complete learner + audience profile.** Teaching into a void defaults to your AI-median explainer voice — abstract, jargon-true, emotionally dead. The cure is grounding every concept in a real, persisted profile of *who is learning and what must change in them*. An incomplete profile is a hard STOP, not a warning.
-
-Run this gate before reframing a single concept:
-
-1. **Locate the teaching profile.** Read the project's root `CLAUDE.md` and follow its short `## Knowledge map` pointer to the full index at `02-DOCS/wiki/index.md`, looking for the entry into `02-DOCS/wiki/teaching/` (the `harness` Karpathy-wiki convention: compiled profile articles live under `02-DOCS/wiki/teaching/`, raw inputs the user pastes live under `02-DOCS/raw/teaching/`). If `CLAUDE.md` is absent, the index entry is missing, or it points nowhere, treat the profile as ABSENT.
-
-2. **Check completeness** against the checklist in `references/learner-grounding.md`. The profile is complete only when every dimension is filled: the LEARNER (level, prior knowledge, pains, desires, current false beliefs, what they want to DO after); the AUDIENCE (same as the buyer or not? live vs recorded? size? context?); the target TRANSFORMATION (the one result, before→after); and constraints/format. **Any empty dimension = INCOMPLETE.**
-
-3. **If ABSENT or INCOMPLETE, STOP and interview the user.** Ask the question script from `references/learner-grounding.md`, **one focused batch at a time** (do not dump all questions at once; ask, wait, persist, then continue). Then:
-   - **a.** Write/update the profile into `02-DOCS/wiki/teaching/` as wiki articles (`learner.md`, `audience.md`, `transformation.md`, `false-beliefs.md`, `constraints.md`, plus an `index.md`), following the article format in `references/learner-grounding.md`. Save any raw material the user pastes (transcripts, outlines, existing slides) verbatim into `02-DOCS/raw/teaching/` and link it from the article's `> Raw:` line. Create the directories if they do not exist.
-   - **b.** Index the teaching profile in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer). Ensure root `CLAUDE.md` carries that short pointer to the index, creating `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet is in `references/learner-grounding.md`.
-
-4. **Only once the profile exists and is complete, proceed.** Cite which articles you used (e.g. "grounded in `02-DOCS/wiki/teaching/learner.md` and `false-beliefs.md`") so every reframing is traceable to a real learner, not an imagined one.
+## Learner grounding (hard gate — read this first)
 
-If the user explicitly says "skip the profile, just rough one concept", you may produce a clearly-labelled `DRAFT (ungrounded — not learner-checked)` and still recommend running the gate before anything ships. That is the only exception, and it must be labelled.
+**Never reframe teaching without a complete learner + audience profile.** Teaching into a void defaults to your AI-median explainer voice — abstract, jargon-true, emotionally dead. An incomplete profile is a hard STOP, not a warning, because everything downstream (which false belief to break, which analogy lands) is derived from it.
 
-Full completeness checklist, the exact batched question script, and the persistence format → `references/learner-grounding.md`.
+1. **Locate the profile.** Read the root `CLAUDE.md`, follow its `## Knowledge map` pointer to `02-DOCS/wiki/index.md`, and look for the entry into `02-DOCS/wiki/teaching/` (the `harness` Karpathy-wiki convention: compiled articles in `02-DOCS/wiki/teaching/`, raw user-pasted material in `02-DOCS/raw/teaching/`). No `CLAUDE.md`, no index entry, or a pointer that goes nowhere = ABSENT.
+2. **Check completeness** against the checklist in `references/learner-grounding.md`: the LEARNER (level, prior knowledge, pains, desires, current false beliefs, what they DO after), the AUDIENCE (same as the buyer? live vs recorded? size? context?), the target TRANSFORMATION (one result, before→after), and constraints/format. **Any empty dimension = INCOMPLETE.**
+3. **If ABSENT or INCOMPLETE, STOP and interview** with the batched question script in `references/learner-grounding.md` — one focused batch at a time, wait, persist, continue. Then write the profile as wiki articles under `02-DOCS/wiki/teaching/` (`learner.md`, `audience.md`, `transformation.md`, `false-beliefs.md`, `constraints.md`, `index.md`), save pasted transcripts/outlines/slides verbatim under `02-DOCS/raw/teaching/` and link them from each article's `> Raw:` line, index the profile in `02-DOCS/wiki/index.md`, and ensure root `CLAUDE.md` carries the short pointer to that index (create it if absent; additive only). Article format and the exact `CLAUDE.md` snippet → `references/learner-grounding.md`.
+4. **Only then proceed**, citing which articles you used ("grounded in `02-DOCS/wiki/teaching/learner.md` and `false-beliefs.md`") so every reframing is traceable to a real learner, not an imagined one.
 
-## The non-negotiables
-
-These are constraints, not preferences. Violating any one is a defect.
-
-1. **Learner profile first.** No reframing before the grounding gate passes (above). Cite the articles you used.
-2. **Every concept gets a story.** A concept taught without a story is a fact the student will forget. Each concept carries at least one Epiphany Bridge beat. (→ `references/brunson-frameworks.md`)
-3. **Every concept gets a name.** An unnamed idea can't be repeated, so it can't be retained. Give each concept a short, ownable, sticky label the student can say out loud. (→ `references/mental-models.md`)
-4. **Every abstraction gets grounded.** No abstract claim ships without a concrete analogy from the learner's own world. "Abstract with no analogy" is a defect. (→ `references/mental-models.md`)
-5. **Break the false belief before installing the new one.** Find the learner's current false belief (vehicle / internal / external), shatter it with a story, *then* teach. Teaching on top of an unbroken false belief bounces off. (→ `references/brunson-frameworks.md`)
-6. **The realization happens in the student.** Tell the epiphany as a journey, don't state the conclusion. The student should *arrive* at the insight, feeling it, not be handed it.
-7. **One Big Domino per module.** Name the single belief that, once believed, makes the rest fall. Build the module to knock it over. (→ `references/brunson-frameworks.md`)
-8. **End every concept on the so-what.** The payoff the student future-paces: what's now possible, what they can do tomorrow. A concept with no so-what is trivia.
-9. **Ground in the learner, not in the expert.** Explain it in the student's world and vocabulary, not the discipline's. Jargon density is a flagged defect. (→ `references/mental-models.md`)
-10. **No fabricated proof or invented credentials.** Stories must be true. If you need a demo/result/proof the user hasn't supplied, mark `[[NEEDS PROOF]]` and ask — never invent a case study or a metric.
+Sole exception: if the user explicitly says "skip the profile, just rough one concept", produce a clearly-labelled `DRAFT (ungrounded — not learner-checked)` and still recommend running the gate before anything ships.
 
 ## The teaching workflow (one pass)
 
 Run in order. Each step feeds the next; skipping one shows up as a flat lesson downstream.
 
-1. **Ground.** Pass the learner-grounding gate. Load learner, audience, transformation, false beliefs, constraints from `02-DOCS/wiki/teaching/`.
-2. **Analyze the content.** Ingest the material; extract the concept list AND the *existing* narrative spine; map ungrounded / jargon-heavy / story-less gaps. → `references/course-analysis.md`.
-3. **Set the Big Domino.** For the module, name the one belief that makes everything else fall, and sequence concepts to build toward it. → `references/brunson-frameworks.md`, `references/course-analysis.md`.
-4. **Per concept, find the false belief** the learner holds (vehicle / internal / external) and the epiphany that breaks it. → `references/brunson-frameworks.md`.
-5. **Run the landing recipe** for each concept: hook → epiphany-bridge story → named mental model → grounded analogy → proof/demo → application (do-this-now) → so-what. → `references/concept-landing-recipe.md`.
-6. **Name the models.** Engineer a sticky, ownable name + a concrete analogy for each. → `references/mental-models.md`.
+1. **Ground.** Pass the gate above. Load learner, audience, transformation, false beliefs, constraints from `02-DOCS/wiki/teaching/` and cite them.
+2. **Analyze the content.** Ingest the material; extract the concept list AND the *existing* narrative spine; map the ungrounded / jargon-heavy / story-less gaps. → `references/course-analysis.md`.
+3. **Set the Big Domino.** Name the one belief per module that makes everything else fall, and sequence concepts to build toward it — not every lesson is equally important. → `references/brunson-frameworks.md`, `references/course-analysis.md`.
+4. **Per concept, find the false belief** the learner holds (vehicle / internal / external) and the epiphany that breaks it. Break it *before* teaching: a lesson landing on an unbroken false belief bounces off. → `references/brunson-frameworks.md`.
+5. **Run the landing recipe** for each concept: hook → epiphany-bridge story → named mental model → grounded analogy → proof/demo → application (do-this-now) → so-what. Every concept gets all seven; a concept with no story is forgotten by tomorrow, and one with no so-what is trivia. → `references/concept-landing-recipe.md`.
+6. **Name the models.** Engineer a sticky, ownable name + a concrete analogy for each — an unnamed idea can't be repeated, so it can't be retained, and an abstraction with no analogy from the learner's own world is a defect. → `references/mental-models.md`.
 7. **Rewrite the narrative spine.** Resequence the whole module/course as a belief-building arc (the Hero's Two Journeys), not a topic dump. → `references/brunson-frameworks.md`, `references/course-analysis.md`.
 8. **Run the QA gate** (below) and `scripts/verify.sh`. Fix every flag or justify it.
 
+Throughout: tell the epiphany as a journey so the student *arrives* at the insight rather than being handed the conclusion, explain it in the student's vocabulary instead of the discipline's, and **never invent proof** — if a demo, result, metric or credential wasn't supplied by the user, mark it `[[NEEDS PROOF]]` and ask.
+
 ## The Expert Secrets toolkit (applied to teaching)
 
 These are the frameworks you run each concept through. Full templates, scripts, and worked teaching examples → `references/brunson-frameworks.md`. Source-confirmed sequence and naming via Brunson's *Expert Secrets* (see citations in that reference).
@@ -96,11 +59,11 @@ These are the frameworks you run each concept through. Full templates, scripts,
 
 ## Analyze the course content
 
-Before reframing, you must *see* what's there. Ingest the material and produce three artifacts. Full method, extraction prompts, and the gap-map template → `references/course-analysis.md`.
+Before reframing you must *see* what's there. Ingest the material and produce three artifacts — full method, extraction prompts and the gap-map template → `references/course-analysis.md`:
 
 1. **Concept inventory** — every distinct idea the material teaches, in teaching order, with a one-line "what the student should be able to DO after this".
-2. **Existing narrative spine** — the story/throughline already present (if any): where it hooks, where it goes flat, whether it builds belief or just stacks topics.
-3. **Gap map** — per concept, flag: `no-story`, `unnamed`, `no-analogy`, `jargon-dense`, `no-application`, `no-so-what`, `belief-not-broken`. These flags drive the rework and mirror exactly what `scripts/verify.sh` greps for.
+2. **Existing narrative spine** — the throughline already present (if any): where it hooks, where it goes flat, whether it builds belief or just stacks topics.
+3. **Gap map** — per concept, flag `no-story`, `unnamed`, `no-analogy`, `jargon-dense`, `no-application`, `no-so-what`, `belief-not-broken`. These flags drive the rework and mirror exactly what `scripts/verify.sh` greps for.
 
 ```text
 GAP MAP (one row per concept)
@@ -137,9 +100,9 @@ Good (landed)   — HOOK: "Ever double-clicked 'Pay' and panicked you'd be charg
                   SO-WHAT: you can now retry fearlessly — failures stop being scary."
 ```
 
-## Anti-patterns / rationalizations → STOP
+## Anti-patterns
 
-| Rationalization | Reality / Fix |
+| Anti-pattern | Reality / fix |
 | --- | --- |
 | "The concept is clear, it doesn't need a story" | Clear ≠ memorable. No story = forgotten by tomorrow. Add an Epiphany Bridge beat. |
 | "Naming it is cutesy / unnecessary" | Unnamed ideas can't be repeated, so they aren't retained. Give it a sticky, ownable name. |
@@ -152,24 +115,9 @@ Good (landed)   — HOOK: "Ever double-clicked 'Pay' and panicked you'd be charg
 | "I'll invent a quick case study to prove it" | Never. Stories must be true. Mark `[[NEEDS PROOF]]` and ask the user. |
 | "Just teach the skill (outer journey)" | The inner journey (identity shift) is why they love the teacher. Teach both. |
 
-## Quick reference
-
-| Lever | Default | Where |
-| --- | --- | --- |
-| Story per concept | mandatory — ≥1 Epiphany Bridge beat | `references/brunson-frameworks.md` |
-| Epiphany beats | backstory → desire → wall → epiphany → new opportunity → result | `references/brunson-frameworks.md` |
-| False beliefs | break vehicle + internal + external before teaching | `references/brunson-frameworks.md` |
-| Big Domino | one per module; aim the arc at it | `references/brunson-frameworks.md` |
-| Named model | short, ownable, repeatable; one per concept | `references/mental-models.md` |
-| Analogy | concrete, from the learner's world | `references/mental-models.md` |
-| Recipe beats | hook → story → model → analogy → proof → application → so-what | `references/concept-landing-recipe.md` |
-| Jargon | flagged when dense / unglossed | `scripts/verify.sh` |
-| End on | the so-what (future-paced payoff) | `references/concept-landing-recipe.md` |
-| Profile | hard gate before any rework | `references/learner-grounding.md` |
-
 ## Teaching QA gate ("did it land?")
 
-Run before claiming done. `scripts/verify.sh` automates the greppable subset.
+Run before claiming done. `scripts/verify.sh` automates the greppable subset (read-only; warns by default, `--strict` to gate CI).
 
 - [ ] Learner + audience profile located, complete, and cited (which articles grounded this).
 - [ ] Big Domino named for the module; the arc is sequenced to knock it over.
@@ -184,22 +132,6 @@ Run before claiming done. `scripts/verify.sh` automates the greppable subset.
 - [ ] No fabricated stories, proof, metrics, or credentials; gaps marked `[[NEEDS PROOF]]`.
 - [ ] The reworked narrative spine builds belief, it doesn't just stack topics.
 
-Automate → `scripts/verify.sh` (read-only; warns by default, `--strict` to gate CI).
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-This skill's 02-DOCS record has two parts, both indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer):
-
-- The **learner + audience profile** at `02-DOCS/wiki/teaching/` — a hard gate (see "Learner grounding" above): if the index lacks the entry or any dimension is empty (learner, audience, transformation, false beliefs, constraints), ask until complete, persist it (raw inputs to `02-DOCS/raw/teaching/`), index it in `02-DOCS/wiki/index.md` and ensure root `CLAUDE.md` carries the short pointer to that index (create `CLAUDE.md` if absent), and only then teach.
-- The **course teaching conventions** at `02-DOCS/wiki/stack/course-storytelling.md` (or alongside the profile under `02-DOCS/wiki/teaching/`) — the established narrative spine, the named mental models already coined, the Big Dominoes per module, and the teacher's Attractive Character. Recorded, not gated.
-
-Create/update both as decisions are made and keep their entries current in `02-DOCS/wiki/index.md` (root `CLAUDE.md` keeps only a short pointer to it). Read them first on every use and keep every reframing consistent with them. If the project has no `02-DOCS` layer at all, skip this section silently and proceed with the in-session profile.
-
-## See Also
+## Project grounding (02-DOCS)
 
-- `../marketing/SKILL.md` — the WORDS that sell the course (value prop, landing copy, launch emails). This skill teaches; that one sells.
-- `../presentations/SKILL.md` — turn the landed lesson into a deck (Marp/Slidev/PPTX, speaker notes).
-- `../design/SKILL.md` — the visual system and pixels behind the slides/diagrams.
-- A content-audit / review-content pass — audit an existing lesson/module/notebook for gaps, redundancy, anachronisms, and storytelling problems (run it first; bring its report here). This skill rebuilds; that pass diagnoses.
-- `../harness/SKILL.md` — the `02-DOCS` Karpathy-wiki convention this skill persists the teaching profile into.
-- References: `references/brunson-frameworks.md`, `references/learner-grounding.md`, `references/mental-models.md`, `references/course-analysis.md`, `references/concept-landing-recipe.md`.
+Beyond the gated learner profile, record the **course teaching conventions** at `02-DOCS/wiki/stack/course-storytelling.md` (or alongside the profile under `02-DOCS/wiki/teaching/`): the established narrative spine, the named mental models already coined, the Big Dominoes per module, and the teacher's Attractive Character. Recorded, not gated — update it as decisions are made, keep its entry current in `02-DOCS/wiki/index.md`, read it first on every use, and keep every reframing consistent with it. The wiki convention itself belongs to `../harness/SKILL.md`. If the project has no `02-DOCS` layer, skip this silently and proceed with the in-session profile.

package/skills/cpp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cpp
-description: "Use when writing, reviewing, modernizing, building, or debugging C++ - RAII and resource lifetime, smart-pointer ownership (unique_ptr/shared_ptr/weak_ptr), move semantics and the Rule of Zero/Five, target-based CMake with FetchContent, and killing undefined behavior with ASan/UBSan/TSan plus clang-tidy. Triggers: \"modernize this C++\", \"who owns this pointer\", \"use-after-free\", \"double free\", \"dangling reference\", \"segfault under load\", \"should this move be noexcept\", \"write a CMakeLists with FetchContent\", .cpp/.hpp/.ixx files, \"revisa este código C++\", \"tengo un segfault\", \"fuga de memoria\". NOT borrow-checker / Result-Option / cargo memory-safety (that is rust)."
+description: "Use when writing, reviewing, modernizing, building, or debugging C++ - RAII and resource lifetime, smart-pointer ownership, move semantics and the Rule of Zero/Five, target-based CMake with FetchContent, and killing undefined behavior with ASan/UBSan/TSan plus clang-tidy. NOT borrow-checker / Result-Option / cargo memory safety (that is rust)."
 tags: [cpp, c++, modern-cpp, raii, cmake]
 recommends: [rust, secure-coding, deployment]
 origin: risco
@@ -23,30 +23,13 @@ behind confirmed compiler support. Compiler matrix:
 | Clang | 13–18 progressively | in progress (Clang 23 dev) | `-std=c++23` / `-std=c++2c` |
 | MSVC | latest | partial | `/std:c++23` / `/std:c++latest` |
 
-## When to use / When NOT to use
-
-**Use when:**
-
-- Authoring or reviewing any `.cpp` / `.cc` / `.hpp` / `.h` / `.ixx` (module) file.
-- Deciding ownership: value / `unique_ptr` / `shared_ptr` / `weak_ptr` / borrowed `span` / `string_view` / `const&`.
-- Modernizing legacy C++: ripping out `new`/`delete`, owning raw pointers, manual loops, C-style casts.
-- Writing or fixing a **CMake** build (target-based, `FetchContent`, presets).
-- Hunting UB: enabling ASan/UBSan/TSan, reading the report, applying the lifetime/bounds/overflow/race fix.
-- Move semantics / Rule of Zero/Five / value-category and `noexcept` questions.
-
-**When NOT to use (delegate):**
-
-- Rust borrow-checker, `Result`/`Option`, cargo, ownership-via-compiler -> [`rust`](../rust/SKILL.md).
-  C++ buys safety with discipline (RAII + smart pointers + sanitizers); do not conflate the mechanisms.
-- Language-agnostic threat modeling, authz, OWASP-class review -> [`secure-coding`](../secure-coding/SKILL.md)
-  (this skill keeps the C++-specific controls: bounds, lifetime, integer overflow, format-string, sanitizers).
-- Containerizing/shipping the binary (Dockerfile, GitHub Actions) -> [`deployment`](../deployment/SKILL.md)
-  (this skill stops at the CMake build + a sanitizer-CI note).
-- Recording per-project C++ conventions in a workspace wiki -> [`harness`](../harness/SKILL.md)
-  (see "Project grounding" below).
-
-The C++-specific memory/UB controls — sanitizers, bounds, lifetime, signed overflow — live
-**here**, not in `secure-coding`.
+Delegate: borrow-checker, `Result`/`Option`, cargo, ownership-via-compiler ->
+[`rust`](../rust/SKILL.md) — C++ buys safety with discipline (RAII + smart pointers +
+sanitizers); do not conflate the mechanisms. Language-agnostic threat modeling, authz,
+OWASP-class review -> [`secure-coding`](../secure-coding/SKILL.md); the C++-specific
+memory/UB controls (bounds, lifetime, integer overflow, format-string, sanitizers) stay
+**here**. Containerizing and shipping the binary -> [`deployment`](../deployment/SKILL.md);
+this skill stops at the CMake build + a sanitizer-CI note.
 
 ## Decision rules
 
@@ -59,20 +42,19 @@ Apply these on every C++ edit:
    only when you need polymorphism, shared lifetime, or a large/stable address. Why: values can't dangle.
 3. **Name the owner.** Exactly one type owns each resource; everyone else borrows. Why: ambiguous
    ownership is how use-after-free is born.
-4. **`make_unique`/`make_shared`, never `new`.** Why: no naked owning pointer ever exists, so there
-   is nothing to forget to `delete`, and it's exception-safe.
-5. **Never an owning raw pointer.** Raw pointers/references are non-owning borrows only. Why: a raw
-   pointer that owns is a leak or a double-free waiting on the next early `return`/throw.
+4. **`make_unique`/`make_shared`, never `new`.** So no naked owning pointer ever exists.
+5. **Never an owning raw pointer.** Raw pointers/references are non-owning borrows only.
 6. **Borrow with `span` / `string_view` / `const T&`.** Pass a view, not a copy or an owner, for
-   read access. Why: zero-copy and the callee provably can't free what it doesn't own.
-7. **`const` and `constexpr` by default.** Make everything you can immutable and compile-time. Why:
-   the compiler enforces what you don't mutate and moves work off the hot path.
+   read access. Why: zero-copy, and the callee provably can't free what it doesn't own.
+7. **`const` and `constexpr` by default.** Why: the compiler enforces what you don't mutate and
+   moves work off the hot path.
 8. **No UB by construction.** No use-after-move, OOB index, signed overflow, uninitialized read, or
-   data race. Why: UB is not a runtime error — the optimizer is licensed to do anything.
+   data race.
 9. **Sanitizers + warnings-as-errors in CI.** Build and test under `-fsanitize=address,undefined`
-   with `-Werror`. Why: most C++ bugs are invisible until a sanitizer or a warning surfaces them.
+   with `-Werror`.
 10. **Target-based CMake only.** `target_link_libraries` / `target_compile_features`, never
-    directory-level `include_directories`/`link_libraries`. Why: directory commands leak flags globally and break composition.
+    directory-level `include_directories`/`link_libraries`. Why: directory commands leak flags
+    globally and break composition.
 
 ## Ownership & smart pointers
 
@@ -277,7 +259,7 @@ bad index is UB, not an exception.
 - **Local gate:** `./scripts/verify.sh` from the project root runs format + an ASan/UBSan,
   warnings-as-errors build + `ctest` + optional tidy/cppcheck. Missing tools are skipped, not failed.
 
-## Anti-patterns / rationalizations -> STOP
+## Anti-patterns
 
 | Rationalization | Reality / Do instead |
 | --- | --- |
@@ -307,41 +289,14 @@ bad index is UB, not an exception.
 | Format | `clang-format -i src/*.cpp` |
 | Static analysis | `clang-tidy -p build src/*.cpp` · `cppcheck --enable=warning src/` |
 | Std flag | GCC/Clang `-std=c++23` (C++26: GCC `-std=c++26`, Clang `-std=c++2c`), MSVC `/std:c++23` |
-| Own a resource | `auto p = std::make_unique<T>(...);` |
-| Borrow a range | `std::span<const T>` / `std::string_view` |
 | Local gate | `./scripts/verify.sh` (run in your project root) |
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md)
-Karpathy wiki), record this project's C++ decisions there and index them in `02-DOCS/wiki/index.md`,
-so the next agent inherits them instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/cpp.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — std version and
-   compiler matrix, CMake layout and presets, the sanitizer/warning policy, and the ownership/error
-   conventions — then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the article
-   (bump its `Updated` date) in the same change.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Technical conventions are
-*recorded, not gated* — never block the task on this.
-
-## See Also
-
-Sibling skills (all resolve under `skills/`):
-
-- [`rust`](../rust/SKILL.md) - the other systems language; compiler-enforced ownership instead of
-  RAII discipline. Any borrow-checker / `Result`-`Option` / cargo question goes there.
-- [`secure-coding`](../secure-coding/SKILL.md) - language-agnostic threat modeling and authz/abuse
-  review (this skill keeps the C++-specific memory/UB controls).
-- [`deployment`](../deployment/SKILL.md) - containerizing and shipping the built binary (this skill
-  stops at the CMake build + a sanitizer-CI note).
-- [`harness`](../harness/SKILL.md) - the `02-DOCS/` workspace wiki where per-project C++ conventions
-  are recorded (see "Project grounding").
-
-Local references (read when):
+## Project grounding (02-DOCS)
 
-- `references/cmake.md` - full target-based CMake template, presets, FetchContent, sanitizer/warning flags.
-- `references/undefined-behavior.md` - the UB catalog, which sanitizer catches each, fixes, ASan-report walkthrough.
-- `references/move-and-templates.md` - value categories, Rule of Five, perfect forwarding, CTAD, C++20 concepts.
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`02-DOCS/wiki/stack/cpp.md` first and stay consistent with it. If it is missing or stale, write
+this project's real choices there — std version and compiler matrix, CMake layout and presets, the
+sanitizer/warning policy, the ownership/error conventions — index it in `02-DOCS/wiki/index.md`
+(the Knowledge map; root `CLAUDE.md` keeps only a pointer to it), and bump its `Updated` date in
+the same change as any convention change. No `02-DOCS/` layer? Skip silently (optionally suggest
+`harness`). Conventions are *recorded, not gated* — never block the task on this.