§ 1 The Pipeline, One Stage at a Time
The whole apparatus
Your main session is the orchestrator. It is your point of contact, and it runs the eight stages in order, moving each stage’s files on to the next. The orchestrator writes the brief itself and hands most of the remaining stages to fresh subagents. One stage is a script, and two are you: approving the plan and receiving the page.
The shape of a stage tells you who does the work: rectangles are agents, the hexagon is a script, and the rounded stages are where you come in. Every stage leaves a file behind that you can open and read.
Stage 1 · Intake brief.md
The orchestrator turns your request into a brief: who the reader is, how long they have, and what they should be able to do afterwards. Every later stage works from the brief, so the more your request says about the reader and the goal, the better the page.
The orchestrator will ask you a question only when it can’t infer the answer.
Stage 2 · Research facts.md
A fresh researcher agent has one job: to collect the facts and sources the rest of the pipeline works from. It stops at a set limit, and every claim it keeps is tied to an objective and recorded with its source, a quote and a confidence.
Things that are true but not needed go to a parking lot, and the raw source material never reaches the agent that writes the page.
Stage 3 · Plan learning-plan.md
An instructional designer turns the brief and the facts into a learning plan: what each section is for, how it is laid out, and where the reader is asked to think. It also draws a wireframe mockup and writes a cut list of what it left out.
This is the stage that makes the output teach. The second half of this page is about the thinking behind it.
Stage 4 · You approve decisions.md
This checkpoint always happens, and always before anything is built. You open the mockup, read the objectives and the cut list, then approve, revise or rescope.
Your answers are recorded as decisions that every later stage must follow, and they stay in the run’s record.
Stage 5 · Build site/
A page builder agent writes the page: the prose, the figures and the exercises. Interactive widgets are built here too, each by its own fresh builder agent; the diagram you are looking at is one of them.
Every builder works from the approved plan and the fact base, not from a chat history.
Stage 6 · Gate page-round-N.json
A script, verify.mjs, opens the page in a real browser through Playwright at 360, 768 and 1280 pixels wide, and fails it on a fixed list of things a machine can check, such as horizontal overflow, broken resources and console errors.
A failure sends the page back to the builder, for a limited number of rounds.
Stage 7 · Review findings.md
Two reviewers check the finished page, each starting in a fresh context and never seeing the builder’s report. One checks accuracy: that every claim on the page is supported by the fact base. The other checks the teaching and the UX: whether the page will actually teach its reader, and whether it is clear to use on a phone and a desktop.
Each finding gets an ID, and blocking ones go back to the builder to be fixed before the page ships.
Stage 8 · Deliver site/ + log.md
You get site/, a static folder ready for any static host. Beside it sits run/, the record of the whole run, starting with log.md.
§ 2 Why It’s Built This Way
None of those stages is unusual on its own. What matters is the shape. Each part of the pipeline exists to prevent a failure you have probably met in your own agent work. Start with how the page gets checked, because a page that teaches something false is worse than no page at all.
Problem 1 · Predict
The builder has finished the page. Before it ships, which check would you trust most to catch a claim it got subtly wrong?
Pick one to see the solution.
Solution.B. Option A is cheap and tempting, but the builder knows what it meant and reads that intent back into the text. Studies of LLM judges also find they rate their own outputs higher than human annotators do (shown on GPT-4 and Llama 2).
C only checks what a machine can check, such as overflow, broken arrowheads and console errors, never whether a sentence is true. Didactician runs C, then B. Whether that split beats one agent reviewing itself hasn’t been measured; it is a hypothesis the design still has to test.
That answer, a reviewer that didn’t write the page, follows from the first of three rules the pipeline is built on: the orchestrator never writes anything itself, so each piece of work, every review included, goes to its own fresh agent. Diagram II redraws the pipeline from Diagram I. As you scroll, each rule is drawn onto the part of the pipeline it protects.
Rule 1 · The orchestrator coordinates, never authors
Your main session is the orchestrator. It talks to you, dispatches the agents and records what they return. It never writes the content, the plan, the site code or a review verdict.
Because the work happens in separate, fresh contexts, two things stay apart. A reviewer never wrote the page it judges, so it reads the page without the author’s reasoning in its head. And the raw research stays with the researcher, so the agent writing the prose isn’t crowded with material it doesn’t need.
Rule 2 · Agents communicate only through files
Agents never talk to each other. Each one is handed a prompt file and returns a report file, both in a fixed structure, and the orchestrator carries the files between them. Each prompt and its report are saved as a pair under run/handoffs/.
Afterwards you can read exactly what every agent was asked and what it reported back, so a run can be audited and resumed.
Rule 3 · You approve before anything expensive
A wrong premise in the plan is the most expensive error in the system, because the build, the gate and the review all inherit it.
So the pipeline puts a human check on the plan while the page is still a mockup. A mistake caught there costs nothing downstream, and saves the time and tokens every later stage would have spent on it.
§ 3 The Idea Underneath: Cognitive Load
Look at this expression, and notice how you read it.
total = sum(x for x in values if x > 0)
A non-programmer
- total
- =
- sum
- x
- for
- in
- values
- if
- >
- 0
about 10 separate pieces to look up and connect
An experienced developer
total = sum(x for x in values if x > 0)one schema: sum the positive numbers
A non-programmer has to track about ten separate pieces, look up what each one means, and work out how each connects to the next. An experienced developer reads the same line in a fraction of a second, as one familiar pattern: sum the positive numbers. For the novice, tracing the syntax uses up their working memory before they have even worked out what the line does. For the developer, long-term memory compresses the whole expression into a single chunk, leaving mental bandwidth free to think about architecture or edge cases.
Cognitive load theory rests on that premise. New information has to pass through a working memory that holds only a little, and only for a short time. What you have already learned lives in long-term memory, and when you use it, it comes back as a single chunk that escapes those limits (Sweller, van Merriënboer & Paas, 2019). An expert doesn’t have a bigger working memory. They have bigger chunks.
Cognitive load is how much of that working memory a page demands, and it comes from two sources.
- Intrinsic load
- comes from the material: how many elements have to be held together at once, relative to what the reader already knows. Better presentation can’t remove it. It changes only when you change what is learned at one time, for instance by teaching the parts before the whole, or when the reader’s expertise grows.
- Extraneous load
- comes from the presentation, and from what the page makes the reader do. It adds nothing to learning, and it is the part a designer controls. Most of the effects researchers report come from changing this kind of load.
Here is extraneous load you can feel: do the same lookup in both versions of Diagram III. Both hold the same information about the pipeline you have just seen.
Try it in A, then in B: what is the stage that writes findings.md called?
ANumbered, names in a key
- 1brief.md
- 2facts.md
- 3learning-plan.md
- 4decisions.md
- 5site/
- 6page-round-N.json
- 7findings.md
- 8log.md
- Key
- 1 Intake
- 2 Research
- 3 Plan
- 4 You approve
- 5 Build
- 6 Gate
- 7 Review
- 8 Deliver
BLabelled on the parts
- Intake brief.md
- Research facts.md
- Plan learning-plan.md
- You approve decisions.md
- Build site/
- Gate page-round-N.json
- Review findings.md
- Deliver log.md
That is the split-attention effect. When readers have to integrate a figure with text placed somewhere else, load goes up and learning suffers; putting the text on the figure removes the effect (Sweller et al., 2019). It’s why Didactician’s figures label the parts directly instead of using a legend, and why every diagram on this page does the same.
§ 4 The Building Blocks
§ 3 gave the reason; these are the tools. The designer builds every page from blocks like these, and chooses each one for what it does to the reader’s load, not for decoration. Each card below is a working example, so try them. Every example uses something you have already met: the code line from § 3, or the pipeline.
These six cards are not a component library. The instructional designer for this page chose them for this material, and a widget builder wrote them from scratch for this page. On another topic, the designer would choose different blocks, and the builders would write new widgets shaped to that content. The skill’s design references describe patterns to draw on, such as completion problems, where the reader fills in a step left blank, but they are ideas to build from, not parts to reuse.
You can also imagine blocks that go further, driven by a live model: a Socratic tutor that questions your answer, or a Feynman-style challenge where you explain the idea back in your own words and have it critiqued. Those are ideas, not features: Didactician’s pages are static files with no backend, and a live model would need one.
§ 5 What You Get
You bring a well-thought-through request, approve a plan, review the page, and get back a folder you can deploy, next to a folder that records how it was made.
- Intake
- Research
- Plan
- You approve
- Build
- Gate
- Review
- Deliver
Here is that second folder, for this page. Start at run/log.md. It is a timeline of the run, and each entry links the files it refers to: the brief, your decisions, and every agent’s prompt and report.
Two limits are worth knowing before you install. Nobody has yet measured whether the separate reviewers catch more than one agent checking its own work; that comparison is still to be run. And a script caps how many rounds and agents a run may use, which limits the token spend, but only if the orchestrator follows the skill’s instructions and calls it. A skipped call would show up in the log; nothing prevents it.
├── site/ ← this page └── run/ ├── log.md ← start here ├── brief.md ├── decisions.md ├── research/ facts, examples ├── plan/ plan, mockup, cuts ├── handoffs/ NN-role.prompt.md │ NN-role.report.md ├── history/ ├── gate/ └── review/ incl. your comments
To try it, copy the skill folder into your project at .claude/skills/didactician/ and ask for a page, saying who it is for and how long they have:
/didactician explain how CRDTs converge, for Hacker News readers, ~10 minutes