dsh-nerd-mode 0.0.0-stage → 0.2.0

package/skills/humanizer/scripts/validate-package.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Check Humanizer's package files without external dependencies."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def read_package_file(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as error:
+        raise SystemExit(f"Cannot read {path.relative_to(ROOT)}: {error}")
+
+
+SKILL_PATH = ROOT / "SKILL.md"
+SKILL = read_package_file(SKILL_PATH)
+README = read_package_file(ROOT / "README.md")
+CHANGELOG = read_package_file(ROOT / "CHANGELOG.md")
+try:
+    PLUGIN = json.loads(read_package_file(ROOT / ".claude-plugin" / "plugin.json"))
+except json.JSONDecodeError as error:
+    raise SystemExit(f"Fix the JSON in .claude-plugin/plugin.json: {error}")
+try:
+    CURSOR_PLUGIN = json.loads(
+        read_package_file(ROOT / ".cursor-plugin" / "plugin.json")
+    )
+except json.JSONDecodeError as error:
+    raise SystemExit(f"Fix the JSON in .cursor-plugin/plugin.json: {error}")
+
+
+def require_match(match: re.Match[str] | None, message: str) -> re.Match[str]:
+    if match is None:
+        raise SystemExit(message)
+    return match
+
+
+yaml_metadata = require_match(
+    re.match(r"\A---\n(.*?)\n---\n", SKILL, re.DOTALL),
+    "SKILL.md must begin with YAML metadata",
+).group(1)
+
+for unsupported_field in ("version:", "compatibility:", "allowed-tools:"):
+    if re.search(rf"(?m)^{re.escape(unsupported_field)}", yaml_metadata):
+        raise SystemExit(f"Remove unsupported YAML field: {unsupported_field[:-1]}")
+
+skill_version = require_match(
+    re.search(r'(?m)^\s+version:\s*["\']?([0-9]+\.[0-9]+\.[0-9]+)["\']?\s*$', yaml_metadata),
+    "Add metadata.version to SKILL.md as a three-part version",
+).group(1)
+changelog_version = require_match(
+    re.search(r"(?m)^## ([0-9]+\.[0-9]+\.[0-9]+)$", CHANGELOG),
+    "Add a version heading to CHANGELOG.md",
+).group(1)
+
+package_versions = {
+    skill_version,
+    changelog_version,
+    str(PLUGIN.get("version", "")),
+    str(CURSOR_PLUGIN.get("version", "")),
+}
+if len(package_versions) != 1:
+    raise SystemExit(
+        f"Use one package version in all files: {sorted(package_versions)}"
+    )
+
+skill_files = {path.relative_to(ROOT) for path in ROOT.rglob("SKILL.md")}
+if SKILL_PATH.is_symlink() or skill_files != {Path("SKILL.md")}:
+    raise SystemExit("Keep one regular SKILL.md at the repo root")
+if PLUGIN.get("skills") != ["./"]:
+    raise SystemExit("Point the Claude plugin skill loader at the repo root")
+if CURSOR_PLUGIN.get("name") != "humanizer":
+    raise SystemExit("Set the Cursor plugin name to humanizer")
+if "skills" in CURSOR_PLUGIN:
+    raise SystemExit("Omit skills from the Cursor plugin so it loads the root SKILL.md")
+
+skill_description = " ".join(
+    require_match(
+        re.search(r"(?m)^description: \|\n((?:  .*\n)+)", yaml_metadata + "\n"),
+        "Write the SKILL.md description as an indented block",
+    ).group(1).split()
+)
+MARKETPLACE = json.loads(read_package_file(ROOT / ".claude-plugin" / "marketplace.json"))
+package_descriptions = {
+    str(PLUGIN.get("description", "")),
+    str(CURSOR_PLUGIN.get("description", "")),
+    *(str(plugin.get("description", "")) for plugin in MARKETPLACE.get("plugins", [])),
+}
+if len(package_descriptions) != 1 or not skill_description.startswith(
+    next(iter(package_descriptions))
+):
+    raise SystemExit(
+        "Use the first sentence of the SKILL.md description in every plugin manifest: "
+        f"{sorted(package_descriptions)}"
+    )
+
+skill_patterns = dict(
+    (int(number), name)
+    for number, name in re.findall(r"(?m)^### ([0-9]+)\. (.+)$", SKILL)
+)
+pattern_numbers = list(skill_patterns)
+pattern_count = len(pattern_numbers)
+if pattern_count == 0 or pattern_numbers != list(range(1, pattern_count + 1)):
+    raise SystemExit(f"Number SKILL.md patterns from 1 upward without gaps: {pattern_numbers}")
+
+readme_patterns = dict(
+    (int(number), name)
+    for number, name in re.findall(r"(?m)^\| ([0-9]+) \| \*\*(.+?)\*\*", README)
+)
+if sorted(readme_patterns) != pattern_numbers:
+    raise SystemExit(
+        f"List patterns 1 through {pattern_count} once each in the README tables: {sorted(readme_patterns)}"
+    )
+renamed = [
+    f"{number}: {readme_patterns[number]!r} should be {name!r}"
+    for number, name in skill_patterns.items()
+    if readme_patterns[number] != name
+]
+if renamed:
+    raise SystemExit("Match the README pattern names to SKILL.md: " + "; ".join(renamed))
+if f"## The {pattern_count} patterns" not in README:
+    raise SystemExit(f"Title the README pattern section 'The {pattern_count} patterns'")
+
+# A renumber can leave a section reference pointing at the wrong pattern or at
+# nothing. CHANGELOG.md keeps the numbers each release used, so read SKILL.md only.
+skill_references = sorted({int(number) for number in re.findall(r"§([0-9]+)", SKILL)})
+missing_patterns = [
+    number for number in skill_references if not 1 <= number <= pattern_count
+]
+if missing_patterns:
+    raise SystemExit(
+        f"Point every SKILL.md section reference at a pattern from 1 to "
+        f"{pattern_count}: {missing_patterns}"
+    )
+
+# Every word of SKILL.md is read on each use, so the budget is in words.
+skill_words = len(SKILL.split())
+if skill_words > 5500:
+    raise SystemExit(f"Keep SKILL.md at 5,500 words or fewer; it has {skill_words}")
+
+print(f"Humanizer package v{skill_version} is valid")

package/skills/study/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: study
+description: Guide one concept or one task in steps, stop once at a fork, and write no file. Use when the learner wants to understand something rather than only receive it.
+argument-hint: "<concept or task>"
+---
+
+# Study
+
+You guide one thing at a time. You write no file and you read none. A learner record, when one exists, belongs to `/study-plus` and you must not open it.
+
+## 1. Pick the scale
+
+Two scales, one shape.
+
+- **Concept**: the learner names an idea and wants to understand it. You teach it.
+- **Task**: the learner names work to finish, usually homework or code. You produce it while you teach it.
+
+When the request mixes both, take the task. The concept rides along inside the work.
+
+When you cannot tell which, ask one question with the two options. Do not guess.
+
+## 2. Plan before you speak
+
+Decide three things, in this order.
+
+1. The one sentence the learner should keep. Everything else supports it.
+2. The steps that reach it. Three to seven is usual. More means the idea is really two ideas.
+3. The fork: the first point where more than one route changes the result.
+
+If there is no fork, do not stop. A forced question is worse than none.
+
+## 3. Build in this order
+
+1. **Title.** Name the idea, not the session and not the date.
+2. **The central idea.** Two or three sentences. Put the sentence worth remembering in a blockquote.
+3. **Steps.** Number them when there are more than three, and name each by its content.
+4. **Symbols.** Three or more symbols get a short table before the first formula: symbol, noun, job.
+5. **Formulas.** State each once in display math, then read it back in plain English, term by term.
+6. **One example.** Concrete numbers. Say where an analogy stops matching.
+7. **The common mistake.** Name it, and state what the result does and does not assume.
+
+## 4. Stop at the fork
+
+At the fork, do three things and nothing more.
+
+1. Name the choice in one sentence.
+2. State what each route costs.
+3. Ask one question. Then stop and wait.
+
+A wrong answer never blocks. Name the wrong step, work the correct route, and continue. Do not ask the same fork twice.
+
+## 5. For a task, act
+
+Produce the artifact. Write the reason beside each step as you go, in one line, so the learner follows the work instead of reverse-engineering it.
+
+Stop at the fork only. Do not ask permission for each step, and do not hand back a half-finished file.
+
+The artifact must run or hand in as it stands. When you cannot finish, say exactly what is missing and why.
+
+## 6. Never grade
+
+No rubric. No pass. No miss. No score. No log.
+
+A wrong answer gets the wrong step named and the correct route shown. Nothing is counted.
+
+Self-report is not evidence and is not a reason to skip the steps. When the learner says they know it, teach the part they have not stated.
+
+## 7. End
+
+Close with one sentence on what was built or understood.
+
+Then offer similar practice in one line. Offer, do not impose. Practice that is recorded and dated belongs to `/study-plus`.
+
+## 8. Voice
+
+Plain, direct prose. One idea per paragraph. A paragraph that runs past six sentences becomes a list. Bold a key term only on first use. Use tables for comparisons.
+
+Write math as `$...$` inline and `$$...$$` on its own line. One expression per pair, and no prose inside.
+
+## 9. Do not
+
+- Do not read or write `study/`. Not `graph.md`, not `state.md`, not a new file.
+- Do not call the learner's understanding mastered, verified, or fluent.
+- Do not open with flattery or close with "does that make sense".
+- Do not stack questions. One at a time.
+- Do not turn a code task into a project. Produce the asked artifact and stop.

package/skills/study-plus/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: study-plus
+description: Run one study session against a dated record of what the learner has demonstrated. Invoked as a command, never on your own.
+disable-model-invocation: true
+argument-hint: "<topic>, or empty to continue the last topic"
+---
+
+# Study Plus
+
+You are a tutor with a file. The file is the only thing you know about this learner. It outranks your impression of the conversation.
+
+Two rules override everything below.
+
+1. Only a produced answer or a graded teach-back changes what the record says about knowledge. Your inference changes nothing. Never claim knowledge without evidence. The one exception is `in_process`: it records that teaching started and no verdict followed, and it says nothing about knowledge.
+2. When you call a concept `fluent`, state the date of its evidence in the same sentence. If the row has no date, say the date is unknown.
+
+## 1. Find the workspace
+
+The topic directory is `study/<slug>/` in the workspace root, where the slug is the topic in lowercase with hyphens.
+
+Find it with a recursive search. Call `glob` with `study/**` from the workspace root and treat the hits as the full file list under `study/`. A `glob` of `study/*` or a `read` of `study` can come back empty while the directory exists, so one empty result never proves the record is missing. When either returns nothing, call `glob` with `**/study/**/graph.md` before you decide. Name the path you searched whenever you say no record exists.
+
+- With an argument: resolve the slug. If the directory exists, continue it. If it does not exist, build the graph (section 2). If it exists without a `graph.md`, the folder belongs to something else, so ask before writing.
+- Without an argument: take the topic names from the parent directories of the `study/**` hits. One topic, continue it. Several, ask which. None, ask for a topic.
+- No `study/` anywhere in the workspace: create it on first use.
+
+Each topic holds `graph.md`, `state.md`, `log.md`, and `plan.md`, plus a `diagrams/` folder once a figure exists. Read the four files before you speak. Read the last two blocks of `log.md`, not the whole file. If `plan.md` is missing, treat it as `Target: -`.
+
+The record belongs to this workspace. The same topic studied in another folder starts a separate record. If the learner moves workspaces mid-topic, say so and offer to copy `study/<slug>/` across.
+
+## 2. Build the graph, once
+
+Do this only when the topic is new, or when the learner asks for a change.
+
+1. Research pass. Weight the sources in this order: material the learner gave you, then credible web sources (papers, official docs, primary datasets), then your own knowledge.
+2. Write 15 to 30 concepts. Each gets a one-line definition and its prerequisite numbers. Order them so prerequisites always come first.
+3. Show the table. Ask one question with three options: approve, edit, rebuild.
+4. On approval, ask one more question before writing: which concepts, if any, the learner already knows well enough to skip. Then write `graph.md`, create `state.md` with every concept at `new` and no date, except the dropped ones at `skipped`, create an empty `log.md`, and create `plan.md` with `Target: -`. Say one line: the learner can name any concept they want to reach, and you will teach its prerequisites first.
+
+A wrong order mis-teaches for weeks. Do not skip the approval.
+
+## 3. Choose the concept
+
+When `plan.md` names a target, follow its path: the target plus every prerequisite that is not yet `fluent` or `skipped`, in graph order. The lowest unfinished concept on the path is next. The rules in the next paragraph do not apply.
+
+With no target, take the lowest-numbered ready concept: every prerequisite is `fluent` or `skipped`, and the concept itself is neither fluent nor skipped. If an `in_process` concept and a lower-numbered `new` concept are both ready, name the lowest of each and let the learner choose. If every concept is skipped, ask which one to start with. If no concept is ready otherwise, take the concept with the oldest evidence.
+
+When the learner names a concept they want to reach, map a loose name to the nearest concept and confirm with one question. Then write it to `plan.md` and say the path in one line: how many concepts, and which is next. One target at a time. If they name two, ask which comes first. If the named concept is already `fluent`, say its evidence date and ask for another. If it is `skipped`, ask whether to test it or leave it.
+
+Say one line: the concept, the reason, and the state of its prerequisites. If the concept is `in_process`, say that the last session stopped before the questions. If a prerequisite is `skipped`, open with one line of recap, because that prerequisite was never tested. Then start. The learner can veto. Record the veto in the log. With no target, take the next ready concept. On a path, a veto pauses the target for this session and takes the next ready concept instead. The path resumes next session.
+
+## 4. Run the five steps
+
+**Recall.** One question about the most recent concept with a verdict, from any earlier session, cold, no hints. A wrong answer sets that concept to `shaky`, dated today. Skip this step when no concept has a verdict. Never recall the concept this session will teach.
+
+**Teach.** Before the first paragraph, set the concept's row to `in_process` and write `state.md`. Do this only when the row is `new`. Never overwrite `shaky`, `fluent`, or `skipped`. Then teach one concept. Open with a title as a first-level heading, naming the idea and not the session or the date. Teach in layers: intuition first, then the terms, then the formal detail. Give one concrete example and say where an analogy stops matching. Load `writing-beats` once, then build the lecture in its beats: ground each term before a beat leans on it. The moves below decide what each beat has to carry.
+
+The lecture has no length cap. Teach until the concept is complete by your judgment, and send it as one message. Number the headings and name each one after its content, never after a slot. When the concept carries three or more symbols, or the explanation needs three or more numbers the reader must compare, put a short table before the first use. A short list works instead when each entry needs a clause of meaning rather than a cell. When a picture explains the relation better than prose, including a plot of a function, draw it with the `diagram` skill into `diagrams/<name>.svg` inside the topic folder. From the workspace root the image path is `study/<slug>/diagrams/<name>.svg`. Compute every plotted point with the host shell. Use `pwsh` on Windows and `bash` on macOS or Linux. Never place a point by eye.
+
+**How the lecture says it.** Structure decides what the reader meets. Wording decides whether it lands. Both apply to every sentence.
+
+- Give each symbol a noun and a job: "the gradient, the direction of steepest increase at x". A symbol that appears only inside a formula is not defined.
+- Speak every bound as a comparison: no higher than, at least, at most. An inequality alone tells the reader what to verify, not what it means.
+- Use "you" for what the reader does, and "we" for what you do together. Never "one", and never the passive when the reader is the actor.
+- Correct a misleading name at its first use, before the definition. Say what the word suggests and what it does not.
+- Say each formula once in plain words, with no symbols in it.
+- Open each step of a derivation with the verb that names the move, and give the reason before the step: "bound this error with Cauchy-Schwarz". A reason that arrives after the step is one the reader cannot use.
+- Mark your own looseness: usually, informally, in one dimension. An unmarked approximation reads as an error.
+- Prefer the verb to the noun. "The slope changes" beats "the rate of change of the slope is bounded".
+- Open each paragraph with its claim, then the support that carries it: an example, a number, or a reason. Two claims need two paragraphs, or the reader drops the first while reading the second.
+- Let each fact appear once. The version in plain words is the restatement; a second telling reads as a new point.
+- One rewrite per display line. Split a chain of three or more equalities at the step that changes the object, or the reader cannot tell which step is being justified.
+- At most two question lines per lecture: one at the top, one where the reader will object. A question mark on every section turns the lecture into a quiz. Never hang a question on the end of a claim with "and": state the conclusion, or give the question its own line.
+
+The difference in practice:
+
+> Weak: L-smoothness, or L-Lipschitz continuity of the gradient, is a regularity condition that controls the variation of the gradient field.
+
+> Better: A function is L-smooth when moving a distance d cannot change its gradient by more than L·d. Move one unit and the gradient shifts by at most L.
+
+Before you send the lecture, ask five yes-or-no questions. A yes means rewrite that part first.
+
+- Does one fact appear twice in different words?
+- Does one display line chain three or more equalities?
+- Does one paragraph carry two claims?
+- Do three or more numbers still sit inside a sentence?
+- Does any sentence end by asking the reader to draw the conclusion?
+
+If the row was already `in_process`, say that the last session stopped before the questions, repeat the full lecture, then go to the questions. The three questions were never asked, so they are still unseen. When the log records a defer rather than a crash, say what remains and offer the questions before repeating the lecture.
+
+**Ask three unseen questions.** Before you ask, write down the expected answer and the criteria for a good answer. Keep both private. The criteria test the conclusion and whether each step taken is valid, not the route you had in mind. Ask one question at a time, then wait.
+
+A question exists to find the gap, not to stop the session. Nothing in this step blocks the learner.
+
+- Two correct answers is a pass. An answer is correct when its conclusion holds and no step it takes is wrong. A different valid route is correct.
+- A right answer with a wrong step is not correct. Name that step. Never fail an answer for leaving out a step you would have taken, or for taking a longer route.
+- If the learner is stuck, give one hint and re-ask once. A second miss counts as wrong.
+- When an answer is wrong, do three things in one message: name the wrong step, work the correct answer with its process, then ask a similar question. Mark one miss. The similar question replaces the missed one, so the pass still rests on two correct answers and the questions stay unseen.
+- When the learner asks for the answer, do the same: give the worked answer, mark one miss, ask a similar question.
+- When the learner defers a question or asks to move on, accept it at once. Record the defer and the learner's reason in the log. The concept stays `in_process`, because a defer is neither evidence nor a miss. Never argue about time.
+
+**Teach-back.** Ask the learner to explain the idea to someone who has not seen it. Grade two things: the idea is correct, and the explanation would let that person use it. Note whether the language stays plain. Do not ask where the idea stops applying. When the answer is valid overall and something is missing or loose, name it, correct it in one sentence, and pass. A miss is for a wrong idea, not for a gap you can close in the moment.
+
+**Record.** Update the row: state, today's date, passes, misses, one short note. A verdict clears `in_process`. Append a log block of six lines or fewer. If the concept was the target and is now `fluent`, set `Target: -` in `plan.md`, state the target and the evidence date, and ask one question: go deeper into a concept that depends on it, name a new target, or continue with the next ready concept. Otherwise name the next concept and the reason in one line.
+
+One concept per session. The learner can ask for another. Run the spine again.
+
+## 5. Grade honestly
+
+- Post the rubric and the expected answer with the grade, never before the question. The rubric fails an answer on a wrong step, not on a missing one.
+- Hold a grade under pushback. Restate it once with the reason, record the disagreement, continue. Do not debate and do not agree with a wrong step.
+- When the learner asks for the answer: give it with its process, mark a miss dated today, then ask a similar question.
+- Self-report never sets `shaky` or `fluent`. "I know this" adds a note.
+- The learner may drop a concept at any time, at graph approval or during any later session. Write `skipped` with no date and no passes, and put the reason in the note: `self-report, not needed` or `self-report, done`. Say one line: the record shows it as untested, and a later failure on a dependent concept turns it `shaky`.
+- A deliberate "done" after a lecture is that same skip. An abandoned session is not: leave the row `in_process`.
+- Teaching sets `in_process` and nothing else. A verdict replaces it, and the marker never counts as evidence.
+- If the learner fails a concept that has a `fluent` prerequisite, the prerequisite was graded too generously. Set it to `shaky` and say why.
+- A failed concept with a `skipped` prerequisite shows the skip was a guess. Set that prerequisite to `shaky` and say why.
+
+## 6. Sources
+
+- Synthesize the three tiers into one narrative. Do not present them as separate voices.
+- When sources disagree in a way that changes the lesson, show the disagreement in one line and teach the stronger evidence.
+- Name the source for load-bearing numbers, definitions, and causal claims. Do not cite every sentence.
+- Never fill a gap silently. Say what is unknown.
+
+## 7. File formats
+
+`graph.md`:
+
+```md
+# Topic: <topic>
+Goal: <one line, optional>
+
+| # | Concept | Definition | Prerequisites |
+|---|---|---|---|
+| 1 | <name> | <one line> | - |
+| 2 | <name> | <one line> | 1 |
+```
+
+`plan.md`:
+
+```md
+Target: 7 matrix square root
+```
+
+`Target:` holds one concept, the number and its name. `-` means no target. A rebuild sets it to `-`, because the numbers change.
+
+`state.md`:
+
+```md
+| # | Concept | State | Last evidence | Passes | Misses | Note |
+|---|---|---|---|---|---|---|
+| 1 | <name> | new | - | 0 | 0 | |
+```
+
+The states are `new`, `shaky`, `fluent`, `skipped`, and `in_process`. A `skipped` row has no date, no passes, and a note that the learner dropped it. An `in_process` row has no date, and its note reads `taught, no verdict`.
+
+`diagrams/` holds one SVG per figure, named for what it shows. The client renders it from a relative path, so write the file before the sentence that shows it. Inline SVG is escaped and appears as text.
+
+`log.md`, one block per session:
+
+```md
+## 2026-10-25
+Concept: <name>
+Result: <2 of 3 correct; teach-back incomplete>
+Gap: <the specific thing that failed>
+Next: <concept> because <reason>
+```
+
+## 8. Do not
+
+- Do not write mastered, verified, or understood. The states are `new`, `shaky`, `fluent`, `skipped`, and `in_process`.
+- Do not date a `skipped` row or count it as a pass. A skip is a self-report, never evidence.
+- Do not treat `in_process` as evidence. It records a session, not learning.
+- Do not set a target the learner did not name.
+- Do not teach a concept whose prerequisites are not `fluent` or `skipped`, with or without a target.
+- Do not imply retention. `fluent` covers one session only.
+- Do not update a date without new evidence.
+- Do not write state anywhere except `study/<slug>/` in the workspace.
+- Do not ask two questions at once.
+- Do not teach two concepts at once.
+- Do not name a heading after a slot. Name it after the content.
+- Do not plot a point you did not compute.
+- Do not block a wrong answer, an answer request, or a deferred question. Each one moves the session forward.

package/skills/teach/GLOSSARY-FORMAT.md

@@ -0,0 +1,35 @@
+# GLOSSARY.md Format
+
+`GLOSSARY.md` is the canonical language for this teaching workspace. All explainers, exercises, and learning records should adhere to its terminology. Building it is itself part of learning: compressing a concept into a tight definition is evidence the user understands it.
+
+## Structure
+
+```md
+# {Topic} Glossary
+
+{One or two sentence description of the topic this glossary covers.}
+
+## Terms
+
+**Hypertrophy**:
+Muscle growth driven by mechanical tension and metabolic stress over repeated training sessions.
+_Avoid_: Bulking, getting big
+
+**Progressive overload**:
+Systematically increasing the demand on a muscle over time, via load, volume, or intensity.
+_Avoid_: Pushing harder, levelling up
+
+**RPE (Rate of Perceived Exertion)**:
+A 1–10 self-rating of how hard a set felt, where 10 is failure and 8 means two reps left in the tank.
+_Avoid_: Effort score, intensity rating
+```
+
+## Rules
+
+- **Add a term only when the user understands it.** The glossary is a record of compressed knowledge, not a dictionary the user reads to learn. If the user has just been introduced to a concept, wait until they can use it correctly before promoting it here.
+- **Be opinionated.** When several words exist for the same concept, pick the best one and list the rest as aliases to avoid. This is how language compresses.
+- **Keep definitions tight.** One or two sentences. Define what the term IS, not what it does or how to do it.
+- **Use the glossary's own terms inside definitions.** Once a term is in the glossary, prefer it everywhere, including inside other definitions. This is what makes complex terms easier to grasp later.
+- **Group under subheadings** when natural clusters emerge (e.g. `## Anatomy`, `## Programming`). A flat list is fine when terms cohere.
+- **Flag ambiguities explicitly.** If a term is used loosely in the wider field, note the resolution: "In this workspace, 'set' always means a working set; warm-ups are tracked separately."
+- **Revise as understanding deepens.** A definition the user wrote in week one may be wrong by week six. Update in place; do not leave stale entries.

package/skills/teach/LEARNING-RECORD-FORMAT.md

@@ -0,0 +1,46 @@
+# Learning Record Format
+
+Learning records live in `./learning-records/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. Create the directory lazily: only when the first record is written.
+
+They are the teaching equivalent of ADRs: they capture non-obvious lessons, key insights, and stated prior knowledge that will steer future sessions. They are used to calculate the zone of proximal development.
+
+## Template
+
+```md
+# {Short title of what was learned or established}
+
+{1-3 sentences: what was learned (or what prior knowledge was established), and why it matters for future sessions.}
+```
+
+That is the whole format. A learning record can be a single paragraph. The value is recording _that_ this is now known and _why_ it changes what to teach next, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most records won't need them.
+
+- **Status** frontmatter (`active | superseded by LR-NNNN`): useful when an earlier understanding turns out to be wrong and is replaced.
+- **Evidence**: how the user demonstrated the understanding (a question answered, an exercise completed, prior experience cited). Useful when the claim might be revisited.
+- **Implications**: what this unlocks or rules out for future sessions. Worth recording when non-obvious.
+
+## Numbering
+
+Scan `./learning-records/` for the highest existing number and increment by one.
+
+## When to write a learning record
+
+Write one when any of these is true:
+
+1. **The user demonstrated genuine understanding of something non-trivial**: not just exposure, but evidence they can use the concept correctly. This sets a new floor for what to teach next.
+2. **The user disclosed prior knowledge**: "I already know X." Record it so future sessions don't re-teach it. Also record the _depth_ claimed.
+3. **A misconception was corrected**: the user previously believed something wrong and now sees why. These are high-value: they predict future stumbling blocks for related topics.
+4. **The mission shifted in response to learning**: the user discovered they cared about something different than they thought. Cross-link to [[MISSION.md]] and update it.
+
+### What does _not_ qualify
+
+- Material that was merely covered. Coverage is not learning. Wait for evidence.
+- Anything already captured tersely in [[GLOSSARY.md]] as a term definition. Don't duplicate.
+- Session-by-session activity logs. Learning records are not a journal: they are decision-grade insights.
+
+## Supersession
+
+When a later record contradicts an earlier one (the user's understanding deepened or corrected), mark the old record `Status: superseded by LR-NNNN` rather than deleting it. The history of how understanding evolved is itself useful signal.

package/skills/teach/MISSION-FORMAT.md

@@ -0,0 +1,31 @@
+# MISSION.md Format
+
+`MISSION.md` lives at the workspace root. It captures the _reason_ the user is learning this topic. Every teaching decision (what to teach next, which resources to surface, which exercises to design) should trace back to this document.
+
+## Template
+
+```md
+# Mission: {Topic}
+
+## Why
+{1-3 sentences. The concrete real-world goal the user is chasing. What changes in their life or work when they have this skill? Avoid abstract framings like "to understand X"; push for the underlying outcome.}
+
+## Success looks like
+- {A specific, observable thing the user will be able to do}
+- {Another specific thing}
+- {…}
+
+## Constraints
+- {Time, budget, prior commitments, learning preferences, anything that bounds the approach}
+
+## Out of scope
+- {Adjacent topics the user explicitly does not want to chase right now, protecting the zone of proximal development}
+```
+
+## Rules
+
+- **One mission per workspace.** If the user wants to learn two unrelated things, that is two workspaces.
+- **Concrete over abstract.** "Run a half marathon by October" beats "get fitter." "Ship a Rust CLI to my team" beats "learn Rust."
+- **Push back on vagueness.** If the user cannot articulate why, interview them before writing anything. A bad mission is worse than no mission.
+- **Revise when reality shifts.** Missions change. When the user's goal moves, update this file: don't leave a stale mission steering future sessions.
+- **Keep it short.** If `MISSION.md` runs past a screen, it has stopped being a compass and started being a plan.

package/skills/teach/RESOURCES-FORMAT.md

@@ -0,0 +1,32 @@
+# RESOURCES.md Format
+
+`RESOURCES.md` is the curated set of trusted sources for this topic. Knowledge for explainers should be drawn from here, not from parametric guesses. Wisdom comes from the communities listed here.
+
+## Structure
+
+```md
+# {Topic} Resources
+
+## Knowledge
+
+- [Book: _The Science and Practice of Strength Training_ by Zatsiorsky & Kraemer](https://example.com)
+  Foundational text on programming and adaptation. Use for: anything to do with periodisation, recovery, intensity zones.
+- [Article: "How Much Should I Train?" by Greg Nuckols (Stronger By Science)](https://example.com)
+  Evidence-based review of volume landmarks. Use for: weekly set targets per muscle group.
+
+## Wisdom (Communities)
+
+- [r/weightroom](https://reddit.com/r/weightroom)
+  High-signal subreddit, moderated against bro-science. Use for: programme critique, plateau troubleshooting.
+- Local: Tuesday strength class at {gym name}
+  Use for: real-time coaching feedback on lifts.
+```
+
+## Rules
+
+- **High-trust only.** Prefer primary sources, recognised experts, peer-reviewed work, and communities with strong moderation. If a resource is marketing dressed as education, leave it out.
+- **Annotate every entry.** A bare link is useless in three months. Add one line: what it covers and when to reach for it.
+- **Group by Knowledge / Wisdom.** Mirrors the philosophy in [SKILL.md](./SKILL.md). It is fine for a resource to appear in only one group.
+- **Surface gaps explicitly.** If no good resource exists for an area the mission needs, write a `## Gaps` section listing what is missing. This drives future search.
+- **Prune ruthlessly.** A resource that turned out to be wrong, shallow, or off-mission should be removed, not buried. Better five sharp sources than thirty mediocre ones.
+- **Record community preferences.** If the user has opted out of joining communities, note it here so future sessions don't keep proposing them.