| name | writing-beats |
| author | mattpocock |
| upstream | mattpocock/skills |
| upstreamPath | skills/in-progress/writing-beats |
| upstreamSha | 9c9f36ccd3995266cd675468af71639c8dde1ec5 |
| lastUpdated | 2026-07-02T01:06:55.000Z |
| tags | ["Writing","Content","Matt Pocock"] |
| description | Writing, exploit — assemble raw material into a journey of beats, grounding each term before a beat leans on it. |
| disable-model-invocation | true |
The user has passed (or will pass) a markdown file of raw material. This is exploit: the exploring is done, the pile is fixed — commit to a path through it and mine the pile to fill each beat.
If the user did not say where to save the article, ask once and remember the path.
Then run a beat-by-beat journey, choose-your-own-adventure style:
- 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–5 until the article reaches a natural end.
Grounding
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.
