--- name: user-learn description: Scaffold a hands-on learning ramp for a topic using the applied-learning method (70% hands-on / 20% mentoring / 10% coursework). Given a topic, creates a self-contained folder with a knowledge base, runnable Jupyter notebooks (graphics included, self-validated by execution), standalone code examples, exercises, project-grounded seed ideas, and a progress tracker. Fans out one sub-agent per file. Use when the user wants to learn a concept by doing, not just reading. Invoke as "/user-learn ". --- # user-learn Turn a topic into a self-contained, **hands-on** learning folder. The method is applied learning — **70% hands-on, 20% mentoring, 10% coursework** — and that ratio is made physical in the folder layout (`70-handson/`, `20-mentoring/`, `10-coursework/`). Two phases: a short **interactive setup** (get topic, confirm scope, ground in the user's real projects), then **parallel authoring** (one background sub-agent per file; notebook agents author AND execute their own notebook until it runs clean). Default output root is the `applied_learning/topics//` repo. The skill is topic-agnostic and reusable for any future concept. ## When to use - The user wants to ramp on a concept (an ML technique, an engineering pattern, a tool) by doing. - The user wants runnable examples + a small reading list + ideas for applying it, not a one-shot explanation. ## When NOT to use - A single specific question — just answer it. - The topic already has a folder under `topics/` — point at it (or offer to extend it). ## Steps ### 1. Get the topic Required argument. Derive a kebab-case slug. Confirm the output path (default `applied_learning/topics//` relative to the dev workspace root). **Existing-topic guard:** Before proceeding, check whether `applied_learning/topics//` already exists. If it does, stop immediately: tell the user the folder exists, offer to extend it or open it, and do NOT recreate it. ### 2. Confirm scope Show the user: the folder layout (below), the planned notebook list (3-5 titles), and the depth (default: knowledge base + 4 notebooks + examples + exercises + seed-ideas). Ask "Proceed?" and wait. (This skill is interactive/user-facing — a confirm here is expected; it is NOT a build-pipeline skill.) Depth knob: `maximal` = full KB + 4-5 notebooks + standalone examples + full exercise set. `lite` = KB + 3 notebooks (skip standalone examples and full exercise set). Default `maximal`. ### 3. Ground Before dispatching, gather the inputs the agents need: - **Canonical-papers list.** Assemble a vetted list of real, well-known papers for the topic. Format: `Author, Year` only. Include an arXiv ID only if you are absolutely certain of it AND mark it explicitly as `(verified)` — e.g. `Kingma & Welling, 2013 (verified: arxiv:1312.6114)`. If uncertain, omit the ID entirely. The seminal-papers agent gets this verbatim so it never fabricates citations. - **Project applications.** Read the `CLAUDE.md` of the user's active workspace projects relevant to the topic (e.g. Alpha4Gate, toybox, sandtable, void_furnace, b2_project_goblin). The seed-ideas agent gets these paths + your notes so applications are concrete and real. - **Notebook plan.** Decide the 3-5 notebooks: order them toy/intuition (numpy-only, always runs) -> from-scratch -> realistic-but-tiny -> advanced concept. Write a one-line spec per notebook (what it shows, what graphic it produces, whether it needs torch). ### 4. Dispatch sub-agents in waves One background sub-agent (`run_in_background: true`) per file, in waves of ~6-10 (a single mega-batch has triggered 529 cascades). One agent each for: - every `10-coursework/*.md` and `20-mentoring/*.md` file (the seminal-papers + seed-ideas agents get the grounding from step 3), - every notebook in `70-handson/notebooks/` (each authors + self-validates its own notebook — see the notebook template), - every `70-handson/examples/*.py` and `exercises.md`. Retry any agent that fails (529, timeout) as a fresh single dispatch. ### 5. Write README + progress After agents complete, glob the folder to confirm every planned file exists. Then write `topics//README.md` (index + suggested learning path, tier-ordered: skim coursework essentials -> work the notebooks in order -> do the exercises -> read seed-ideas) and `20-mentoring/progress.md` (a checklist derived from the ACTUAL notebooks + exercises produced). ### 6. Goblin hook `applied_learning` is already a `b2_project_goblin` target (it has a `CLAUDE.md` + `plan.md`). End by noting `uv run goblin suggest applied_learning` (from the goblin repo) as the "what should I learn/do next" nudge — goblin ranks next steps grounded in the topic folders. Do not modify goblin's source. ### 7. Report Files written, any agent retries, notebook execution results (all green?), and one suggested next action (open the README, run a notebook, run `goblin suggest`). ## Output layout ```text topics// ├── README.md ├── 10-coursework/ │ ├── essentials.md # core concepts + math prereqs, intuition-first │ ├── papers-seminal.md # foundational papers (from the vetted list — no fabricated ids) │ ├── papers-frontier.md # interesting/applied/recent papers tuned to the user's projects │ ├── related-topics.md # adjacency map; each entry 2-3 line explainer + link │ └── courses-resources.md # courses, lectures, blogs, textbooks ├── 20-mentoring/ │ ├── seed-ideas.md # concrete applications in the user's REAL projects (grounded) │ ├── open-questions.md # discussion prompts to work through with a mentor / Claude │ └── progress.md # self-tracking checklist (written by the orchestrator in step 5) └── 70-handson/ ├── notebooks/ # NN-*.ipynb, runnable, executed-in-place (graphics embedded) ├── examples/ # standalone runnable .py scripts └── exercises.md # graded exercises with hints + solution pointers ``` ## Sub-agent prompt templates ### Knowledge-base / mentoring file agent **Every KB agent prompt must include the 300–700 word hard limit from the CONSTRAINTS block below. Do not abbreviate or omit it for any file in the batch.** ```text Write ONE markdown file at /. Topic: "". This file is the (e.g. "essentials", "seminal papers", "seed ideas"). READ for grounding (don't invent): . ...> : ...> CONTENT: . CONSTRAINTS: - Terse, reference tone, written to be grepped later. **300–700 words (hard limit).** - No emojis. No padding (one honest line beats a filler paragraph). - No fabricated citations or arXiv ids. Author+year is always safe; link arxiv.org/abs/ only when certain. - Markdown links relative from the file's location. Write with the Write tool. Reply: "Wrote " + notes. ``` ### Notebook agent (authors AND self-validates) **Every notebook agent prompt must include the full SELF-VALIDATE block below. Do not abbreviate or omit it for any notebook in the batch.** ```text Author ONE Jupyter notebook at /70-handson/notebooks/-.ipynb, then make it run clean. Topic: "". This notebook: . REQUIREMENTS: - Valid nbformat v4 JSON. Most reliable: write a small builder script using `nbformat` (assemble markdown+code cells, then `nbf.write(...)`), run it, then delete it. If you use a builder or any temp file, give it a UNIQUE name that includes this notebook's `NN-` prefix (e.g. `_build_.py`) and delete it immediately after — parallel sibling notebook agents run concurrently in the SAME notebooks dir and collide on shared temp filenames. (Alternatively write the `.ipynb` directly via the Write tool or NotebookEdit.) - Markdown cells explain the intuition before each code cell. Code cells are small and readable. - MUST produce at least one matplotlib figure (the graphic). - MUST run headless on CPU in seconds: tiny models (small nets, few epochs), dataset SUBSETS, set a seed. . - ASCII only in any print()/string (Windows cp1252). - Use only deps declared in the repo pyproject.toml (numpy, matplotlib, scikit-learn, torch CPU, torchvision). Datasets download under ./data (gitignored). SELF-VALIDATE (required — do not reply until green): uv run --project jupyter nbconvert --to notebook --execute --inplace "" Run it. If it errors, fix the notebook and re-run until exit 0. Execution embeds the figures into the committed file. Reply: "Wrote + executed -.ipynb (exit 0)" + wall-clock + any caveat. If you cannot get it green after reasonable effort, say so explicitly with the error — do NOT claim success. ``` ### Example-script agent ```text Write ONE standalone script at /70-handson/examples/.py — a minimal, self-contained, runnable distillation of the core idea of "". CONSTRAINTS: runs headless on CPU in seconds (tiny); ASCII-only print(); only declared deps; a top docstring saying what it does and how to run it (`uv run python .py`). Validate by running it once (exit 0). Reply with the result. ``` ## Constraints - **Runnable code only** — no pseudocode in notebooks/examples. The execute-in-place gate is the proof. - **No fabricated references.** Seed the seminal-papers agent with a vetted list; instruct author+year over uncertain ids. - **Tiny + fast** — everything runs headless on CPU in seconds, or it doesn't ship. - **70/20/10 layout** — always the numeric-prefix folders. - **Ground seed-ideas in real projects** — read their CLAUDE.md; generic "you could use this for X" is the failure mode. - **No emojis. Terse reference tone.** ## Limitations - Dispatching all agents in one mega-message has hit 529 cascades — wave them (~6-10). - Notebook agents that can't reach exit 0 must say so, not fake success — the orchestrator re-checks with `scripts/run_all_notebooks.sh`. - Skipping the grounding step produces generic blog-post content and hand-wavy seed ideas. - torch install must be done (`uv sync`) before notebook agents run, or every execute fails. - Pre-fetch any SHARED dataset once (e.g. `torchvision.datasets.MNIST(...download=True)`) BEFORE dispatching notebook agents — concurrent first-downloads to the same dir race and corrupt. Point notebooks at a single repo-root `data/` dir (walk up to `pyproject.toml`), not a per-notebook copy.