Socratic Learning System
You do not understand something until you can produce it. Explain it in plain words, work it by hand, teach it back, find the place you go vague, fill that place, repeat. This is the Feynman method, and it is the only method that has ever worked. The technique is centuries old. The tools for it do not exist.
Every instrument we actually have is built for the opposite verb. The IDE is built for writing code that runs, not for working through an idea. The article and the blog are built for publishing a thought after the thinking is finished. Notion, docs, slides, this site as it stands today, all of them are display surfaces. They are for showing a result. None of them is for the production that is understanding. You learn by producing, and the world hands you tools for consuming and tools for publishing, with nothing in the gap between. Understanding leaks out of that gap.
This system is the instrument that gap has been missing. It does two things at once, and they are the same act seen from two sides. It is a notebook flexible enough that working through a thing stays the point, where the producing happens. And it is a textbook dense enough that the finished page proves you understood, to a recruiter, a peer, anyone who lands on it. An article site can only carry the claim that you did something. A textbook page carries the thing itself, worked to the floor, which is the only proof of understanding there is. Producing teaches you; the artifact it leaves credentials you. You do not learn for the second reason, but the first reason produces the second for free.
The wrong verb
Right now the pipeline is IDE to article. You write in an editor built for code, and it renders to a page built for reading. Both ends are wrong, and the format in the middle is the cause.
Markdown is the lowest common denominator that survives the trip from editor to page. It carries prose down a single column and not much else. Code sits on the page as a picture of code; it cannot run. Math is an afterthought. A drawing is a file you link to. The page that results is article-shaped: airy, linear, made to be read top to bottom and skimmed. That is the correct shape for an essay. It is the wrong shape for learning, because learning is not reading.
A textbook is the opposite of an article. It is dense. A figure sits beside the paragraph that needs it. A worked example interrupts the prose because the prose was building toward it. The page is packed because you are meant to work through it, not glide over it. The current site cannot make that page. It is good at displaying and bad at density, and it is worst of all at the thing that matters most: it is a place you publish to after the thinking is done, not a place you think in.
The right verb
The pipeline should be notebook to textbook.
A notebook is built for working through. The unit is not the document, it is the cell: a thought in progress. A cell holds prose, or runnable code, or a hand-drawn derivation, or math, and the cells sit in the order you understood them. You produce in a notebook. That is its whole reason to exist, and it is the exact verb the Feynman loop needs.
A textbook is what the notebook becomes when the working-through is done. Dense, figure beside text, worked, permanent, and teachable to the next person, which is the last step of the method and the one everyone skips. The session does not get summarized into a page afterward. The session is the page. You learn in it, and what you learned is what ships, with the structure of the thinking still intact instead of flattened into prose.
So the two surfaces both serve learning instead of both fighting it. The place you write and the place that publishes are the same cell-structured thing, and nothing lossy happens in between.
What the system does
Three parts, in the order a session runs them.
It establishes what to learn before it teaches. A topic is not a curriculum. A paper, a pattern, a job’s list of required skills: each is a request for a scope, not a scope. The first move is always to turn the topic into the smallest ordered set of learnable units, dependencies first, and to lay the page out as headers with no content under them. The content arrives later, from your production, not from a wall of text written at you.
It teaches by making you produce, never by lecturing. One small question at a time, sized just above what you last showed you could do. You answer by producing: a sentence, a cell of code, a derivation on the tablet. The right answer gets captured onto the page as it happens. The wrong answer shrinks the question. The page fills in as a side effect of the drilling. There is no separate write-up step, because the drilling was the writing.
It keeps what you made. The page ships to the site and stays there, dense and worked and public. The next session starts from it. Most learning evaporates the moment the session ends; this does not, because the artifact and the understanding are the same object. The site stops being a place to read finished thoughts and becomes a place where understanding accumulates.
Why now
A year of five or six classes with a job underneath it does not yield to effort. Effort does not scale to that load. Throughput does: how fast a thing you do not understand becomes a thing you own, and how reliably it stays owned. The method for that is settled. The instrument for it is not, so it gets built once, now, while there is room, and then it runs for the whole stretch. You sharpen the axe before the tree falls, not during.
The build, in three steps
The philosophy above is the spec. The rest is for the coding agent.
It is three steps and not two because today there is an awkward thing in the middle. The flow runs through markdown and MDX, an intermediate that does neither job well: it is unpleasant to write in, and it is not the final HTML either, just a lossy way-station between them. The project is to pull that middle apart and do each half properly.
1. Replace the intermediate with a real input format. The thing you write in. Plain-text, cell-structured, holding prose and code and images and math in one surface. The leading candidate is MyST Markdown: a markdown superset with real cell and directive structure, plain-text on disk so git diffs stay clean and an agent can read every change live. Plain-text is a hard requirement, not a preference, because the workflow is one screen authoring and one screen running an AI that watches the file. A JSON notebook format breaks that; a text format does not.
2. Adopt a local app that renders that input well. The authoring surface. Do not build one. Find the existing tool that renders the format nicely and reads file changes cleanly, so the loop is: you produce in the editor, the AI on the other screen sees the change and drills the next question. The only hard constraint is that constraint from step 1, plain-text on disk that an agent can watch.
3. Render the output to beautiful HTML in the site. This is a design problem, not a format problem. The output is HTML, integrated into the existing site shell, theme, and sidebar. The work is making it look like a dense, worked textbook rather than an airy article: figure beside text, worked examples set into the prose, the page packed to be studied. Separate from steps 1 and 2 entirely. The input format does not dictate the HTML, and the HTML’s density does not constrain the input.
Notes for whoever builds it. MyST ships a native JavaScript parser built on the markdown-it dependency the site already has, so step 3 can slot into the loader’s existing markdown-to-HTML step (site/src/loaders/wikiLoader.ts, near line 238, mirrored in wikiLoaderAll.ts) rather than bolting on a separate renderer. The drawing-to-page path is the existing :asset[] directive: draw on the tablet in any open-source app, export a PNG, drop it in. In-page code execution (Pyodide, client-side, since the site is static) is a later phase, not part of the first three. Whatever the build, keep it flag-gated and opt-in per page so the hundreds of existing pages cannot regress: prove it on one real learning page, then expand.