diff --git a/README.md b/README.md index acc3149..ef6c973 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ You're not trying to become a software engineer. You want coding as a superpower The output is a **single HTML file** — no dependencies, no setup, works offline. It includes: +- **Learner-aware teaching** — examples, metaphors, and quiz scenarios can adapt to your background, such as explaining software flows through clinical handoffs for a doctor - **Scroll-based modules** with progress tracking and keyboard navigation - **Code ↔ Plain English translations** — real code on the left, what it means on the right Code translation block @@ -72,6 +73,10 @@ No "What does API stand for?" Instead: "A user reports stale data after switchin Each concept gets a metaphor that fits *that specific idea*. A database is a library with a card catalog. Auth is a bouncer checking IDs. API rate limiting is a nightclub with a capacity limit. Never the same metaphor twice. +### Memory-aware personalization + +If the assistant already knows relevant context about the learner, it should use that context as a teaching lens. A doctor might see debugging framed as clinical triage, data flow as a patient handoff, and reliability as preventing dropped follow-up. Sensitive personal details should never be copied into the course. + ### Original code only Code snippets are exact copies from the real codebase — never modified or simplified. The learner should be able to open the actual file and see the same code they learned from. diff --git a/SKILL.md b/SKILL.md index aedeb5b..ea70675 100644 --- a/SKILL.md +++ b/SKILL.md @@ -38,6 +38,27 @@ The target learner is a **"vibe coder"** — someone who builds software by inst **They are NOT trying to become software engineers.** They want coding as a superpower that amplifies what they're already good at. They don't need to write code from scratch — they need to *read* it, *understand* it, and *direct* it. +## Learner Memory Profile + +Before analyzing the codebase, build a lightweight learner profile from the current conversation and any locally available memory/context the user has already granted access to. Use it to tailor the course to the learner's real background, goals, and vocabulary. + +**What to capture:** +- Their professional domain or lived context (for example, doctor, designer, founder, teacher, researcher) +- Their current technical comfort level and recurring tools +- Their likely goals for understanding this codebase +- Domain language they already know well, and technical language that still needs tooltips + +**How to use it:** +- Choose metaphors and scenarios that map to the learner's domain. For a doctor, a data pipeline might feel like triage, handoff, chart review, or lab-result routing. +- Make quizzes reflect decisions they might actually face in that role. For a doctor, ask where they would inspect a broken clinical scheduling flow, not a generic shopping cart. +- Keep glossary tooltips focused on unfamiliar software terms. Do not over-explain domain terms the learner likely already knows. +- Explain why each technical idea helps them steer AI coding tools in their own work. + +**Privacy and safety rules:** +- Do not invent personal facts. If the profile is thin, use neutral examples or ask one concise question only when personalization would materially improve the course. +- Do not include private memory contents, sensitive personal details, credentials, medical records, or contact information in the generated course. +- Treat the profile as a teaching lens, not as course content. The course should feel personally relevant without exposing the learner's private history. + ## Why This Approach Works This skill inverts traditional CS education. The old model is: memorize concepts for years → eventually build something → finally see the point (most people quit before step 3). This model is: **build something first → experience it working → now understand how it works.** @@ -56,6 +77,8 @@ The directory-based output is intentional: separating CSS/JS from content means Before writing course HTML, deeply understand the codebase. Read all the key files, trace the data flows, identify the "cast of characters" (main components/modules), and map how they communicate. Thoroughness here pays off — the more you understand, the better the course. +Start by writing a private 3-5 bullet learner memory profile for yourself. Do not place it in the final course unless the user explicitly asks for it. Let it shape the examples, metaphors, tooltips, and quiz scenarios throughout the curriculum. + **What to extract:** - The main "actors" (components, services, modules) and their responsibilities - The primary user journey (what happens when someone uses the app end-to-end) diff --git a/references/content-philosophy.md b/references/content-philosophy.md index 79fae1a..055b3e4 100644 --- a/references/content-philosophy.md +++ b/references/content-philosophy.md @@ -38,6 +38,8 @@ No walls of text. Each screen within a module teaches exactly one idea. If you n ### Metaphors First, Then Reality Introduce every new concept with a metaphor from everyday life. Then immediately ground it: "In our code, this looks like..." The metaphor builds intuition; the code grounds it in reality. +When the learner has a known professional background or personal learning context, use that as the first place to look for metaphors. A clinician may understand queues, handoffs, escalation, triage, chart review, and lab-result routing faster than generic consumer-app examples. A founder may understand funnels, constraints, and operating dashboards. The metaphor should make the technical idea feel closer to the learner's own judgment. + **Critical: No recycled metaphors.** Do NOT default to "restaurant" for everything — that's the #1 crutch. Each concept deserves its own metaphor that feels natural to *that specific idea*. A database is a library with a card catalog. Auth is a bouncer checking IDs. An event loop is an air traffic controller. Message passing is a postal system. API rate limiting is a nightclub with a capacity limit. Pick the metaphor that makes the concept click, not the one that's easiest to reach for. If you catch yourself using "restaurant" or "kitchen" more than once in a course, stop and rethink. ### Learn by Tracing @@ -87,3 +89,5 @@ The goal of learning is practical application — being able to *do something* w **How many quizzes:** One per module, placed at the end after the learner has seen all the content. 3-5 questions per quiz. Each question should make the learner pause and *think*, not just pick the obvious answer. **Deciding what concepts are worth quizzing:** Quiz the things that would actually help someone in practice — architecture understanding ("where does this logic live and why?"), debugging intuition ("what would cause this symptom?"), and decision-making ("what's the tradeoff here?"). If a concept won't help someone debug a problem, steer an AI assistant, or make an architectural decision, it's not worth quizzing. + +**Personalized scenarios:** When a learner profile is available, write at least one quiz per course around a realistic situation from that learner's world. For a doctor, this might be a broken shift-scheduling screen, stale patient-list data, or a handoff workflow that lost context. Keep the technical lesson unchanged; only adapt the story so the learner can reason from familiar experience.