Writing rules
Reference: Writing stages
The rule as we use it, word for word. Every piece on the site is edited against it.
Binding for every piece of prose written in this workspace, alongside the least-first and short-words references. Read it in full before writing anything longer than one paragraph.
The rule
Write in three stages: map, rough draft, final draft. Each stage is its own written output, and each has a gate. Do not start a stage until the one before it passes its gate.
Least First decides how much goes in. This file decides when. The map is where the loop runs on cheap bullets, so the drafts start from a shape that already holds.
Scale it to the piece
- One or two sentences (a message, a commit line, a UI string): the thesis line is the map. Write it, run the least-first loop, ship.
- One paragraph: the map is the reader line, the thesis and the list of points. Rough and final can be one stage.
- Anything longer: all three stages, all three gates.
When unsure, do the map. It is the cheapest stage to get wrong and the most costly to skip.
Stage 1: the map
A bulleted map of the whole piece: what it says, in what order, backed by what. It stops tangents before they are written and is the thing you check the drafts against.
What goes in it
- Reader line.
Reader: <who>. After reading, they will: <act>.(see least-first) - Thesis. One full sentence. This is layer 0.
- Topics, in order. One per body paragraph, each written as a full sentence. These become the topic sentences, so they are layer 1.
- Sub-points under each topic, as short fragments. Each one answers a reader question on the least-first valid list.
- Evidence under each sub-point: the source, value, quote, command or example you will use. Name it. "Data shows"
is not evidence. If you don't have it yet, write
[NEED: what]. - Seam note on every topic after the first:
picks up: <term or claim from the topic before>. - Close. The so-what, the decision or the next step. Or
none, if the piece ends on its last topic. - Parked. Points you thought of that failed the gate. Keep them here so they stop pulling at the draft.
Example
Reader: a new teammate. After reading, they will clean their own export and load it.
Thesis: Run clean.py on any export before you load it, because raw exports break the loader in three known ways.
1. Raw exports break the loader in three ways.
- dates in two formats
- evidence: the loader's error text, quoted
- blank rows at the end
- evidence: row count before and after
- a stray header row mid-file
- evidence: [NEED: which export does this]
2. clean.py fixes all three in one run. picks up: "three ways"
- the command
- evidence: the exact line to paste
- what it changes, so they can check
3. It won't fix a missing column, so check that first. picks up: "fixes all three"
- how to check
- evidence: the column list
Close: next step is the load command.
Parked: why the exports are bad upstream (doesn't change what they do)
Gate
- Reader line and thesis are filled in.
- Read the topic sentences alone, in order. They make the case as a short essay.
- Every topic serves the thesis. Every sub-point traces to a valid reader question.
- Every topic after the first has a seam note, and the note is true.
- Depth is even: no topic has far more sub-points than its neighbors without a reason.
- Evidence is named. Open
[NEED]items are listed, and you know how to fill them or will drop the point. - Nothing in Parked has crept back in.
Checkpoint. If the piece is long or costly to redo, show the map to whoever asked for it before drafting. It is the cheapest point to change course.
Stage 2: the rough draft
Turn the map into prose, in one go, with the map open.
- One paragraph per topic. The topic sentence from the map opens it, picking up from the seam note.
- Follow the map. Write the sub-points and evidence it lists, in its order.
- No new points. If one comes up while writing, stop. Put it in the map, run the map gate on it, then write it. If it fails, it goes to Parked.
- Order changes go through the map too. Move it in the map first, then move the paragraph.
- Whole sentences, plain words, no polish. Word choice is a final-draft job. Paragraphs may still be cut, and polishing them first is wasted work.
- Don't invent missing evidence. Leave
[NEED: what]in the text.
Gate
- Every map topic and sub-point is in the draft. Nothing is in the draft that isn't in the map.
- Run the least-first loop from layer 2: list the reader's questions per paragraph, keep only the valid ones, answer each with the least that works.
- Read top to bottom in one go. Every place you stopped to ask how you got there is marked.
- Every
[NEED]is filled, or its point is cut from both the draft and the map.
Stage 3: the final draft
Work from the outside in. Each step can undo the one after it, so the order matters.
- Structure. Check the draft against the map one more time. If they differ, decide which is right and make them match.
- Flow. Fix every seam the rough-draft read marked (see Flow in least-first). Fix order before writing bridges.
- Paragraphs. Delete, merge and depth tests. Re-read every seam a cut leaves.
- Sentences. Delete test, throat-clearing, closing restates, hedges, chains.
- Words. The short-words pass.
- Tooling. Run the project's prose checker, if it has one (
python3 scripts/check_short_words.py), and fix every hit. - Read-through. Top to bottom, as the reader, in one sitting.
Gate
- No
[NEED]orTODOleft. - Draft and map agree.
- Self-checks in least-first and short-words pass.
- The read-through had no stops.
- For high-stakes pieces: a separate reader who saw only the reader line and the final draft found no questions they would have to ask.
Where the stages live
Write the map and the rough draft to scratch files next to your work, named <piece>.map.md and
<piece>.rough.md. Keep them out of the shipped tree so the checker doesn't scan bullets and [NEED] marks. Delete
them once the final ships.
Each stage is a separate write. Never produce the map and the draft in the same step. The gap between them is the point: it is where the map gets checked.
Traps
Mapping in your head. A map you didn't write down can't be checked, and it drifts as you draft.
A map that is a draft. If the bullets are full paragraphs, it is a rough draft with dashes in front. Topics are sentences. Everything below them is fragments.
Drafting around the map. The draft grows a point the map doesn't have, and the map never hears about it. Every change goes through the map.
Polishing the rough draft. Fixing words in a paragraph that the final pass cuts.
Skipping the gate because the stage felt fine. The gate is the deadline. Run it every time.