@ericrisco/rsc 0.1.43 → 0.1.45

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.

package/skills/csharp-dotnet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: csharp-dotnet
-description: "Use when writing, reviewing, testing, or shipping C# / .NET code, ASP.NET Core APIs, or EF Core data access — editing .cs/.csproj/.sln files, designing minimal APIs vs controllers, fixing async correctness, or structuring a dotnet solution. Triggers: 'build a .NET API', 'is this idiomatic C#', 'should this DTO be a record', 'my endpoint hangs/deadlocks under load' (sync-over-async), 'EF query hits the DB once per row' (N+1), 'set up xUnit + WebApplicationFactory', 'crea una API en .NET', 'revisa este código C# antes de hacer deploy'. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs)."
+description: "Use when writing, reviewing, testing, or shipping C# / .NET code — ASP.NET Core APIs (minimal APIs vs controllers), EF Core data access, async correctness, solution layout in .cs/.csproj/.sln. NOT a Java/Spring backend (that is spring-boot), NOT a Node/TypeScript backend (that is nestjs), NOT framework-neutral REST naming (that is api-design)."
 tags: [csharp, dotnet, aspnetcore, efcore, async]
 recommends: [postgresdb, secure-coding, deployment]
 origin: risco
@@ -20,17 +20,6 @@ support but shorter-lived. Features gate on the target framework moniker (TFM):
 use a C# 14 feature (`field`, extension members, null-conditional assignment), say
 which TFM it requires.
 
-## When to use
-
-- Authoring/reviewing/refactoring any `.cs`, `.csproj`, or `.sln`.
-- ASP.NET Core: minimal APIs vs controllers, route groups, endpoint filters,
-  validation, ProblemDetails, OpenAPI.
-- EF Core: `DbContext` design, LINQ queries, migrations, tracking, N+1.
-- async/await correctness: `CancellationToken` plumbing, `async void`, deadlocks,
-  `IAsyncEnumerable`, `ValueTask`.
-- `dotnet` CLI workflow, solution layout, NuGet, central package management.
-- Idiom review: records, pattern matching, nullable reference types (NRT).
-
 ## When NOT to use — delegate
 
 | Situation | Route to |
@@ -45,29 +34,7 @@ which TFM it requires.
 
 The .NET *expression* of an API contract and async correctness live HERE. Resource
 naming theory lives in `api-design`; the JVM and Node counterparts are `spring-boot`
-and `nestjs`. Only `secure-coding`, `postgresdb`, `deployment`, and `harness` exist on
-disk as siblings, so only those are linked as `../<id>/SKILL.md`.
-
-## Decision rules — apply on every C# edit
-
-1. **NRT on.** `<Nullable>enable</Nullable>` in the csproj. Why: the compiler turns
-   whole classes of `NullReferenceException` into build-time warnings. Never disable it
-   to silence a warning — fix the nullability.
-2. **Async all the way, flow the token.** I/O methods are `async Task`, every call is
-   `await`ed, and a `CancellationToken` threads from the endpoint down to
-   `SaveChangesAsync`/queries/HTTP calls. Why: a dropped token means requests keep
-   running after the client gives up.
-3. **Records for DTOs and immutable data.** `public record ProductDto(int Id, string Name);`.
-   Why: value equality + `with` expressions + concise; never reuse an EF entity as the
-   wire DTO (see anti-patterns).
-4. **Parameterize every query.** EF LINQ and `FromSql` interpolation parameterize for
-   you; never string-concatenate SQL. Why: SQL injection.
-5. **Deterministic disposal.** `using`/`await using` (or `using` declarations) for
-   anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections/handles.
-6. **One `DbContext` per request (scoped).** Why: `DbContext` is not thread-safe;
-   sharing across requests corrupts change tracking.
-7. **Minimal APIs for new services** unless you need MVC features (views, model
-   binders, action filters at scale). Why: less ceremony, first-class in .NET 10.
+and `nestjs`.
 
 ## Project & solution layout + dotnet CLI
 
@@ -101,6 +68,10 @@ Central package management: turn it on with `<ManagePackageVersionsCentrally>tru
 and list versions once in `Directory.Packages.props`. Why: one source of truth, no
 version drift across projects.
 
+NRT on for every project — `<Nullable>enable</Nullable>` in `Directory.Build.props`.
+Why: the compiler turns whole classes of `NullReferenceException` into build-time
+warnings. Never disable it to silence a warning — fix the nullability.
+
 ## Modern C# idioms (C# 14 / .NET 10)
 
 DTO as a record, not a class:
@@ -113,6 +84,9 @@ public class ProductDto { public int Id { get; set; } public string Name { get;
 public record ProductDto(int Id, string Name, decimal Price);
 ```
 
+Why: value equality, `with` expressions, no boilerplate — and never reuse an EF entity
+as the wire DTO (see anti-patterns).
+
 Pattern matching over if-chains:
 
 ```csharp
@@ -154,6 +128,9 @@ Prefer NRT annotations over defensive null checks: declare `string? note` when n
 valid and let the compiler force callers to handle it, instead of `if (x == null)`
 guards scattered everywhere.
 
+Dispose deterministically: `using` / `await using` (or `using` declarations) for
+anything `IDisposable`/`IAsyncDisposable`. Why: leaked connections and handles.
+
 ## async/await correctness
 
 This is the highest-leverage area to get right. Core rules in body; the full catalog
@@ -173,7 +150,9 @@ public IActionResult Get() => Ok(_svc.LoadAsync().Result);
 public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.LoadAsync(ct));
 ```
 
-- **Flow `CancellationToken`** from the endpoint into every async call.
+- **Flow `CancellationToken`** from the endpoint down into every async call —
+  `SaveChangesAsync`, queries, outbound HTTP. Why: a dropped token means the request
+  keeps running after the client gives up.
 - **`ValueTask` only for hot paths** that usually complete synchronously; default to
   `Task`. Never `await` a `ValueTask` twice.
 - **`IAsyncEnumerable<T>` for streaming** results instead of materializing a huge list.
@@ -182,6 +161,7 @@ public async Task<IActionResult> Get(CancellationToken ct) => Ok(await _svc.Load
 
 Decision: **minimal API** for new services; **controllers** only when you need MVC
 machinery (model binding conventions, action filters at scale, views). Both can coexist.
+Why minimal by default: less ceremony, first-class in .NET 10.
 
 Production minimal API shape — route group + DataAnnotations validation (built in for
 minimal API parameters in .NET 10) + ProblemDetails + OpenAPI 3.1:
@@ -215,7 +195,8 @@ app.Run();
 ```
 
 DI lifetimes: `Singleton` (one for the app), `Scoped` (one per request — `DbContext`
-lives here), `Transient` (new each resolve). Never inject a `Scoped` service into a
+lives here; it is not thread-safe, so sharing one across requests corrupts change
+tracking), `Transient` (new each resolve). Never inject a `Scoped` service into a
 `Singleton` (captive dependency — see anti-patterns). Middleware ordering, endpoint
 filters, the options pattern, and auth defaults are in **references/aspnetcore.md**.
 
@@ -252,7 +233,7 @@ Keep only the .NET-specific controls here; threat modeling and OWASP review go t
 `../secure-coding/SKILL.md`.
 
 - **Parameterized data access** — EF LINQ / parameterized `FromSql` / ADO.NET
-  `SqlParameter`. Never concatenate user input into SQL.
+  `SqlParameter`. Never concatenate user input into SQL. Why: SQL injection.
 - **Secrets** — `dotnet user-secrets` in dev, Key Vault / environment in prod. Never in
   `appsettings.json` or source.
 - **Antiforgery** for cookie-auth browser POSTs; **Data Protection** for cookies/tokens

package/skills/customer-support/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: customer-support
-description: "Use when a support ticket, email, or chat lands and you must handle it well and fast — triage it (priority + queue + intent), draft a reply that does not read like a template, decide whether to escalate to a human, and keep the SLA clock from blowing. Also when an angry or churn-risk customer needs a de-escalation reply, when you need a canned-response library, or when you must set or audit first-response and resolution SLA targets. Triggers: 'a customer says our app is down and they're losing money', 'this user is threatening to cancel and leave a bad review, draft a reply', 'give me canned replies for common questions', 'what response times should we promise', 'redacta una respuesta para un cliente enfadado', 'tracta aquest ticket de suport'. NOT writing the help-center article the ticket links to (that is technical-writing), not the new-customer welcome flow (that is client-onboarding), not a win-back program (that is retention), and not building the auto-answer bot (that is chatbot)."
+description: "Use when a live support ticket needs triage (intent, P1–P4 priority, SLA clock), an on-voice reply, not a raw template, de-escalation of an angry or churn-risk customer, or escalation with a handoff packet. NOT the help-center article it links to (that is `technical-writing`), a win-back program (`retention`), or the auto-answer bot (`chatbot`)."
 tags: [customer-support, helpdesk, ticket-triage, sla, escalation, macros, de-escalation, csat]
 recommends: [technical-writing, client-onboarding, retention, chatbot, rag, brand-voice]
 origin: risco
@@ -8,22 +8,8 @@ origin: risco
 
 # Customer Support — Run the Desk on a Live Ticket
 
-*A ticket just came in. Triage it, answer it on-voice, escalate it if it needs a human, and keep the SLA from blowing. This skill handles the live ticket — it does not write the article the ticket links to.*
-
 You own the **support desk as an operation**: take an incoming ticket, assign priority and intent, start the SLA clock, draft the reply (macro or bespoke), enforce tone, and decide escalation with a clean handoff. The output is a triaged, answered ticket — human judgment, not a code artifact.
 
-## What this owns vs. what it does not
-
-| You reach for this when | Route elsewhere when |
-|---|---|
-| A ticket needs triage, a reply, an escalation call | Authoring the KB / help-center article a ticket links to → `technical-writing` |
-| One churn-risk ticket needs de-escalation **now** | Running a win-back / renewal **program** → `retention` |
-| You need macros, SLA targets, a handoff packet | Onboarding a brand-new customer (welcome, activation) → `client-onboarding` |
-| A human (or assisted) reply against the brand voice | Building the autonomous auto-answer bot → `chatbot` + `rag` |
-| Applying the voice to this reply | Authoring the voice guide itself → [`../brand-voice/SKILL.md`](../brand-voice/SKILL.md) |
-
-The line: **writing the help-center article a ticket links to is `technical-writing`'s job; `customer-support` only handles the live ticket.** This skill *consumes* the KB to answer; it never writes the docs.
-
 ## The triage-to-reply loop (the spine)
 
 Run every ticket through these six steps in order. Skipping triage to "just reply fast" is how you send the wrong tone to a P1.
@@ -37,29 +23,22 @@ Run every ticket through these six steps in order. Skipping triage to "just repl
 6 Escalate or send  →  trigger met? hand off with the packet. else send + log.
 ```
 
-The branch is at step 6. Use this table to decide priority and the first-response target, then whether the ticket leaves your hands:
+## Priority, SLA, and the escalation call
 
-| Signal in the ticket | Priority | First-response target | Escalate? |
-|---|---|---|---|
-| Production down / data loss / many users blocked | P1 | 15–30 min | Yes → tier-2/eng + the packet |
-| Enterprise/VIP account, or "cancel / refund / lawyer / unacceptable" | P1–P2 | 30 min – 1 h | Yes → owner + tier-2 |
-| One user blocked, no workaround | P2 | 1–2 h | Only if unresolved past target |
-| Question with a workaround, billing query | P3 | 4–8 h | No, unless policy claim is unverifiable |
-| FAQ, cosmetic, feature request | P4 | ~1 business day | No |
+The branch is at step 6. This table sets priority, both SLA clocks, and whether the ticket leaves your hands:
 
-**Why pick the FRT target before drafting:** the SLA decides your tone and length. A P1 gets a two-line acknowledgment in 20 minutes, not a polished essay in two hours.
+| Signal in the ticket | Priority | First response (FRT) | Resolution target | Escalate? |
+|---|---|---|---|---|
+| Production down / data loss / payments broken / many users blocked | P1 critical | 15–30 min | ASAP, status updates every 30–60 min | Yes → tier-2/eng + the packet |
+| Enterprise/VIP account, or "cancel / refund / lawyer / unacceptable" | P1–P2 | 30 min – 1 h | Same business day | Yes → owner + tier-2 |
+| One user blocked, no workaround | P2 high | 1–2 h | Same business day | Only if unresolved past target |
+| Question with a workaround, billing query | P3 medium | 4–8 h | 1–2 business days | No, unless policy claim is unverifiable |
+| FAQ, cosmetic, feature request | P4 low | ~1 business day | Best effort | No |
 
-## Priority and SLA
+**Why pick the FRT target before drafting:** the SLA decides your tone and length. A P1 gets a two-line acknowledgment in 20 minutes, not a polished essay in two hours.
 
 Use **3–4 priority tiers, never a flat SLA.** Too many tiers confuse the desk; too few don't differentiate the outage from the typo (Emailmeter / Hiver, 2026-06-02).
 
-| Priority | Meaning | First-response (FRT) | Resolution target |
-|---|---|---|---|
-| P1 critical | Outage, data loss, payments broken | 15–30 min | ASAP, status updates every 30–60 min |
-| P2 high | One user blocked, no workaround | 1–2 h | Same business day |
-| P3 medium | Workaround exists, billing/how-to | 4–8 h | 1–2 business days |
-| P4 low | Cosmetic, FAQ, feature request | ~1 business day | Best effort |
-
 **Acknowledge fast even when you cannot resolve fast.** First-response and resolution are *separate, linked* SLAs: FRT sets the expectation, resolution is the outcome. 89% of customers feel valued by a fast first response even when the full fix takes longer (getMonetizely / Hiver, 2026-06-02). So: acknowledge inside the FRT window with an honest "here's what I know and when I'll update you," then resolve honestly. Never go silent to wait for a perfect answer.
 
 Full P1–P4 matrix by channel (email/chat/phone) lives in [`references/macros-and-sla.md`](references/macros-and-sla.md).
@@ -126,6 +105,8 @@ Banned phrases — they escalate, not de-escalate:
 
 Checklist before send: feeling acknowledged · first-person ownership · one timed next step · no banned phrase · no `{{placeholder}}` left.
 
+De-escalating *this* ticket is the job here; running a win-back or renewal **program** is `retention`.
+
 ## Escalation
 
 Escalate on **explicit conditions, not vibes.** Standard tiers: T1 frontline/common, T2 specialist/complex, T3 engineering or exec/critical (Kapture / Hiver, 2026-06-02). Hand off when any trigger fires:
@@ -158,7 +139,7 @@ The full escalation matrix (trigger → tier → owner) is in [`references/macro
 - If it is not in the KB, say "let me confirm" and escalate — do not fill the gap with a plausible guess.
 - Deflection is **bounded by KB quality.** Triage-only without a strong KB deflects ~20–30%; well-organized KBs push assisted/auto resolution to 50–80% (Zendesk / Intercom / Fini Labs, 2026-06-02). A bad answer fast is worse than a correct answer slightly slower.
 
-If the article the customer needs does not exist, that is a `technical-writing` job — flag the gap, don't write the doc inside the ticket.
+This skill *consumes* the KB; it never writes it. If the article the customer needs does not exist, flag the gap — authoring it is a `technical-writing` job, and building the autonomous auto-answer bot on top of the KB is `chatbot` + `rag`.
 
 ## Metrics — what to watch and when
 
@@ -187,7 +168,3 @@ Rule of thumb: optimize **FRT** for reassurance (the customer feeling handled),
 | "Please calm down" / "as I said" | Tells them their feeling is the fault | De-escalation moves; banned-phrase swaps |
 | Promise a fix you can't verify | Breaks trust when it slips | Promise the *next update time*, not the fix |
 | Chase NPS off a single ticket | Wrong altitude metric | CSAT/FCR per ticket; NPS at relationship level |
-
-## References
-
-- [`references/macros-and-sla.md`](references/macros-and-sla.md) — the full macro skeleton library (10+ ready replies), the complete P1–P4 SLA matrix by channel, and the escalation matrix with the handoff-packet template. Pulled out because it is long, branch-specific lookup material you reach for mid-ticket, not flow you read top-to-bottom.