Topic Explainer
Explain a complex topic clearly for a defined audience: a planner pins the audience, their assumed prior knowledge, and the concepts that must be taught, a researcher gathers accurate facts and good analogies with sources, and a copywriter writes a progressively-structured explainer that builds from fundamentals to the full picture. The ordering matters because an explainer written without a fixed audience either condescends or loses people, and one written without a concept map skips a prerequisite; locking the audience and a concept dependency order first guarantees the explanation actually lands. Use this for 'explain X like I'm a beginner/expert', concept explainers, how-it-works guides, ELI5/ELI-expert pieces, and turning a hard topic into an accessible read.
Steps
Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.
- Scope the explainerplannerentry
audience, assumed knowledge, and concept dependency order
Show working prompt
1. Pin the target audience and their assumed prior knowledge in one sentence (e.g. 'curious non-technical adult, no math'), and the target length. 2. List the concepts that MUST be understood, then order them by dependency (what must be taught before what) — this is the explainer's spine. 3. Decide the structure: a one-line 'what it is', then fundamentals, then the mechanism, then implications/examples, then a recap; flag where an analogy or a worked example is needed. 4. Write an acceptance-criteria checklist (e.g. 'no concept is used before it is introduced', 'jargon is defined on first use', 'at least 2 concrete examples or analogies', 'a reader at the assumed level could follow it', 'every factual claim is accurate and cited where non-obvious'). 5. Record decisions. Call write_task_note with the audience, concept order, structure, and checklist; write the same to notes/scope.md.
- Gather facts & analogiesresearcher
accurate facts, examples, and analogies with sources
Show working prompt
1. For each concept in the dependency order, gather accurate facts into notes/facts.md with sources [n] for any non-obvious or quantitative claim, prioritizing authoritative explanations. 2. Find or craft at least two concrete examples and one strong analogy per hard concept, and sanity-check that each analogy does not mislead (note where it breaks down). 3. Note common misconceptions about the topic so the explainer can pre-empt them. 4. Verify any figure or mechanism against a reliable source; mark uncertain points UNVERIFIED. Good looks like a fact file where every concept has accurate grounding plus a teaching device. Do not write the explainer yet.
- Write the explainercopywriter
progressive explainer from fundamentals to full picture
Show working prompt
1. Write explainer.md following the locked concept order: a crisp one-line 'what it is', then build up concept by concept so nothing is referenced before it is introduced. 2. Define every term on first use, and use the gathered examples/analogies to make hard concepts concrete (note where an analogy breaks down). 3. Pre-empt the common misconceptions. 4. Match the assumed-knowledge level exactly — neither condescend nor assume away prerequisites. 5. Cite non-obvious facts [n] and end with a short recap of the key takeaways. 6. On a loop-back, fix only the named gaps. 7. Call write_task_note with the explainer path and which criteria now pass.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Open explainer.md and check EACH criterion PASS/FAIL: (1) no concept is used before it is introduced (trace the dependency order from notes/scope.md); (2) every jargon term is defined on first use; (3) at least two concrete examples or analogies appear and any analogy notes where it breaks down; (4) it matches the assumed-knowledge level — readable by the target audience without condescension; (5) non-obvious facts are cited and accurate (spot-check 2 against notes/facts.md); (6) a recap of takeaways closes it. An explainer that drops a prerequisite, leaves jargon undefined, or misstates a fact FAILS. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "write" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.
Triggers
Phrases that suggest this craftbook to a crew.
- explain this topic
- how does X work
- explain like I'm a beginner
- make this concept accessible
- write an explainer on
Source
View this craftbook on GitHub · MIT license