user-learn

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 <topic>".

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/<slug>/ 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/<slug>/ relative to the dev workspace root).

Existing-topic guard: Before proceeding, check whether applied_learning/topics/<slug>/ 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/<slug>/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

topics/<slug>/
├── 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.

Write ONE markdown file at <ABS-PATH>/<FILE>.

Topic: "<TOPIC>". This file is the <ROLE> (e.g. "essentials", "seminal papers", "seed ideas").

READ for grounding (don't invent): <repo CLAUDE.md; for seed-ideas, the listed project CLAUDE.md paths; for seminal-papers, USE THE VETTED LIST BELOW VERBATIM>.

<for papers-seminal.md: VETTED CANONICAL PAPERS (use these, do not add ids you are unsure of):
- <Author Year — Title — arxiv id if certain> ...>

<for seed-ideas.md: TARGET PROJECTS + ANGLE:
- <project>: <one-line of how the topic could apply, grounded in what you read> ...>

CONTENT: <what this specific file should contain — see Output layout comments>.

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/<id> only when certain.
- Markdown links relative from the file's location.

Write with the Write tool. Reply: "Wrote <FILE>" + 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.

Author ONE Jupyter notebook at <ABS-PATH>/70-handson/notebooks/<NN>-<slug>.ipynb, then make it run clean.

Topic: "<TOPIC>". This notebook: <one-line spec — what it teaches + the graphic it produces>.

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_<NN>.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. <if numpy-only: do NOT import torch>.
- 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 <APPLIED-LEARNING-ROOT> jupyter nbconvert --to notebook --execute --inplace "<ABS-PATH-TO-NB>"
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 <NN>-<slug>.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

Write ONE standalone script at <ABS-PATH>/70-handson/examples/<name>.py — a minimal, self-contained, runnable distillation of the core idea of "<TOPIC>".

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