NodeJSmith Beats
Exploit: the exploring is done, the pile is fixed — commit to a path through it and mine the pile to fill each beat, choose-your-own-adventure style. Pairs with mine-fragments (explore) and mine-shape (the paragraph-by-paragraph alternative to this skill).
Arguments
$ARGUMENTS — path to the raw material file. If empty, ask the user for it — and mention /mine-fragments as the typical way to produce one, if they don't have raw material yet. If a given path doesn't resolve, say so explicitly and offer the same suggestion rather than surfacing a raw tool error.
The raw material file is treated as the input pile — anything from a tidy list of fragments to a wall of unstructured prose to a transcript. The format does not matter. Read it end-to-end before doing anything else. Do not edit the raw material file — it is read-only to this skill.
If the user did not say where to save the article, run get-skill-tmpdir mine-beats, write to <dir>/article.md, and tell the user where it's saved — do not ask once and rely on remembering the path for the rest of the session, since the session may not persist.
The Loop
- Establish the prerequisites. Before any beats, settle with the user what the audience already knows walking in — the concepts that are grounded from the start. Everything else must be grounded by a beat before a later beat can use it. See Grounding.
- Write 2–3 candidate starting beats, drawn from the raw material. Each is a different entry point into the article. Each may only lean on grounded concepts; note what new concepts each one grounds. Show the user the beats before writing to the article file. The user picks one. Preview what beats that pick unlocks — as if the user is seeing a little way down the path.
- Once the user picks a starting beat, write only that beat to the article file. A beat may be one sentence or several paragraphs — whatever that beat naturally is. Stop there.
- Re-read the article file from disk. Then offer 2–3 candidate next beats — different directions the journey could pivot to from where the article now stands. Each must be reachable from the current grounded set; note what each one grounds.
- Loop steps 3–4 until the article reaches a natural end.
Grounding
This grounding discipline is duplicated (not shared) with mine-shape's Grounding section by design (no side files for this pipeline) — if you change the grounding model here, update the other file too.
Every concept has to be grounded before a beat can lean on it: the audience either walked in knowing it or met it in an earlier beat. A beat that reaches for an ungrounded concept loses the reader — that is the one move the journey can't make. The unit is the concept, not the word for it: a beat can lean on an idea the reader lacks even with no jargon in sight. Where a concept has a name — a term — grounding it means landing the idea and the term together.
A concept gets grounded one of two ways:
- Prerequisite — grounded before the first beat. The audience brings it. Fixed at the start.
- Introduced — a beat establishes it, and from then on it's grounded for every later beat.
So each beat does two jobs: it requires concepts that are already grounded, and it grounds new ones. Keep a running list of what's grounded so far, and update it each time a beat lands.
This is what shapes the choose-your-own-adventure. A candidate beat is only reachable if everything it requires is already grounded; picking a beat that grounds concept X unlocks every beat that was waiting on X. When you offer next beats, they must all be reachable from the current grounded set — and say what each one grounds, so the user can see which paths it opens.
The big lever is what you make a prerequisite versus what you ground inside the piece. Demand too much up front and you shut out readers who don't have it; ground too much inside and the early beats drown in definitions. Settle this with the user when you establish prerequisites, and revisit it whenever a tempting beat turns out to require a concept nothing has grounded yet — the fix is either a grounding beat before it, or promoting the concept to a prerequisite.
What Is a Beat
A beat is one move in the journey. It does one thing — sets a scene, lands a point, asks a question, drops an aside, twists the angle. Then it stops, leaving the reader at a place where the next beat can pivot.
A beat is sized by what it needs:
- A single sentence if that's all the move is ("And then nothing happened for three weeks.").
- A short paragraph if the move needs setup.
- Multiple paragraphs if the beat is a self-contained vignette, argument, or example.
If a "beat" needs five paragraphs and three subheadings, it's not a beat — it's two beats glued together. Split it.
Pulling from the Pile
Pull material from the raw pile to populate 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 empty. Most piles will have leftover fragments that don't make it in. That is fine; that is the point of having more raw material than you need.
Writing Rhythm
- Append one beat at a time. Never write ahead.
- Re-read the article file from disk before every write. Preserve user edits absolutely.
- If the user edits a previous beat substantially, let it change what comes next.
- If the user says "rewrite that beat" or "go back and try a different beat 3", do it — edit in place, leave the rest alone.