The user has passed in (or is about to pass in) a raw material file in markdown format. This is exploit: the exploration is done, the material pile is fixed: promise a path through it, then mine the material pile to fill each beat.
If the user has not said where to save the article, ask once and remember the path.
Then proceed on a beat-by-beat choose-your-own-adventure journey:
- Set the prerequisites. Before any beat, first establish with the user what the reader already knows on entry: those concepts that are **grounded** from the very start. Every other concept must be grounded by some beat before a later beat can use it. SeeGrounding。
- Distill 2–3 candidates from the raw material for thestarting beat. Each beat is a different entry point into the article. Each beat may depend only on already grounded concepts; note what new concept each beat grounds. Show the beats to the user before writing to the article file. The user chooses one. Preview which subsequent beats that beat unlocks: let the user see as if a short stretch of road ahead.
- After the user chooses the starting beat, writeonly this one beatto the article file. A beat can be a sentence or several paragraphs: it depends on how much space the beat naturally needs. That is all for now.
- Re-read the article file from disk. Then offer 2–3 candidates for thenext beat: different directions the article can turn from where it currently is. Each candidate beat must be reachable from the currently grounded set; note what each beat grounds.
- Loop steps 3–5 until the article reaches a natural ending.
Grounding
Everyconceptmust begroundedbefore it is used by a beat: the reader either already knows it on entry, or has encountered it in a previous beat. A beat that touches an ungrounded concept loses the reader: this is the only mistake that cannot be made in the journey. The unit is the concept, not the word: a beat can depend on an idea the reader lacks even if there is no jargon at all. When a concept has a name: aterm: grounding means landing both the idea and its term.
A concept is grounded in one of two ways:
- Prerequisite: grounded before the first beat. The reader brings it. Fixed at the start.
- Introduced: a beat establishes it, and thereafter it is grounded for all subsequent beats.
So every beat carries two things: itrequiresalready grounded concepts, and at the same time itgroundsnew concepts. Keep tracking the current grounded list, and update it when each beat lands.
This is exactly what shapes the choose-your-own-adventure core. A candidate beat is only reachable when all the concepts it requires are already grounded; choosing a beat that grounds concept X unlocks all beats waiting on X. When you supply the next beat, they must all be reachable from the currently grounded set: and state what each beat grounds, so the user can see which paths it opens.
The biggest lever is the trade-off between what you set as a prerequisite and what you ground inside the article. Requiring too many prerequisites shuts out readers who lack them; grounding too much internally drowns early beats in definitions. Negotiate this with the user when setting prerequisites, and revisit it when an enticing beat suddenly requires a concept that nothing has grounded yet: the fix is either to add a grounding beat before it, or to promote that concept to a prerequisite.
What a beat is
A beat is one step in the journey. It does one thing: sets a scene, makes a point, asks a question, takes an aside, shifts an angle. Then it stops, leaving the reader at a position where the next beat can turn.
The size of a beat depends on its needs:
- If the step needs only one sentence, it is one sentence ("And then nothing happened for three weeks.").
- If the step needs setup, it is a short paragraph.
- If the beat is a self-contained fragment, argument, or example, it can be multiple paragraphs.
If a "beat" needs five paragraphs and three subheadings, it is not one beat: it is two beats stuck together. Split it apart.
Extracting from the material pile
Extract material from the raw material pile to fill each beat. You can paraphrase, split, reorganize, or quote. The material pile is your quarry.
Ending the journey
The article ends when the journey is complete: not when the material pile is emptied. Most material piles will have leftover fragments that were not used. That is fine; this is exactly the point of having more raw material than you need.
Writing rhythm
- Append only one beat at a time. Never write ahead.
- Before each write, reread the article file from disk. Absolutely preserve the user's edits.
- If the user substantially revises a previous beat, let the subsequent content adjust accordingly.
- If the user says "rewrite that beat" or "go back and try a different beat 3", do it: edit in place, leave the rest unchanged.