The user has passed in (or will pass in) a raw material markdown file. This is exploit: the exploration is done, the pile is fixed——promise a path through it and dig into the pile to fill each beat.
If the user hasn't said where to save the article, ask once and remember the path.
Then run the beat-by-beat journey in choose-your-own-adventure style:
- Establish the prerequisites. Before any beat, first establish with the user what the audience already knows on entry——the concepts that are already grounded from the start. Everything else must first be grounded by some beat before a later beat can use it. See Grounding。
- Write 2-3 candidate starting beatsfrom the raw material. Each is a different entry into the article. Each may rely only on already-grounded concepts; note which concepts each beat newly grounds. Show these beats to the user before writing them into the article file. The user picks one. Preview which beats will be unlocked by choosing this beat——like letting the user see a little way down the path ahead.
- After the user picks the starting beat, write onlythat beatinto the article file. A beat can be a sentence or several paragraphs, as long as it naturally needs. Stop when done.
- Re-read the article file from disk. Then offer 2-3 candidate next beats——that is, different directions the journey can pivot from where the article currently is. Each must be reachable from the currently grounded set; note what each beat grounds.
- Loop steps 3-5 until the article ends naturally.
Grounding
Every concept must first be groundedbefore a beat can rely on it: the audience either knows it on entry, or has encountered it in an earlier beat. A beat that reaches for an ungrounded concept loses the reader——this is the one move the journey cannot make. The unit is the concept, not its wording: even with no term in sight, a beat may rely on an idea the reader does not have. When a concept has a name——a term——grounding it means landing the idea and the term together.
A concept is grounded in one of two ways:
- Prerequisite —— grounded before the first beat. The audience brings it. Fix it at the start.
- Introduced —— some beat establishes it, and from then on it is grounded for every later beat.
So every beat does two things: itneedsalready-grounded concepts, and grounds new concepts. Keep a list of what has been grounded so far, and update it as each beat lands.
This is exactly what shapes the choose-your-own-adventure. A candidate beat is reachable only when everything it needs is already grounded; choosing a beat that grounds concept X unlocks all beats waiting on X. When you offer next beats, they must all be reachable from the currently grounded set——and state what each grounds, so the user can see which paths it opens.
The key lever is what you set as a prerequisite and what you ground inside the article. If the opening demands too much, it shuts out readers who don't have those things; if too much is grounded internally, the early beats drown in definitions. Settle this with the user when you establish prerequisites, and revisit it whenever an alluring beat turns out to need a concept that nothing has grounded yet—the fix is either to put a grounding beat before it or to promote that concept to a prerequisite.
What is a beat
A beat is one step in the journey. It does one thing: set the scene, land a point, pose a question, insert an aside, turn the angle. Then it stops, leaving the reader at a position where the next beat can pivot.
The size of a beat is determined by the action it needs to accomplish:
- If the action is a single sentence, it's a single sentence ("And then nothing happened for three weeks.").
- If it needs setup, it's a short paragraph.
- If the beat is a self-contained vignette, argument, or example, it can be multiple paragraphs.
If a "beat" needs five paragraphs and three subheadings, it's not a beat but two beats stuck together. Split it apart.
Pulling from the pile
Draw material from the raw pile to fill each beat. You can paraphrase, split, recombine, or quote. The pile is a quarry.
Ending the journey
The article ends when the journey is complete, not when the pile is used up. Most piles will have leftover fragments that never get used. That's fine; having more raw material than actually needed is the whole point.
Writing rhythm
- Append one beat at a time. Never write ahead.
- Re-read the article file from disk before every write. Absolutely preserve user edits.
- If the user has substantially edited an earlier beat, let it change what gets written next.
- If the user says "rewrite that beat" or "go back and try a different beat 3," do it: edit in place, don't touch the rest.