Editing fixes sentences. Revision rewrites the spec. Most writers spend their careers doing the first when the second is what is wrong.
I learned the difference the hard way. Twice. Once with words. Once with images.
The words: I wrote an essay in a voice that was not mine. I edited it for two weeks. I polished every sentence. The essay still did not sound like me. The voice was the problem. The voice is a spec. I had been editing the output of a wrong spec. I deleted the essay. I rewrote the spec. The new draft was sharper in one afternoon than the edited draft had been after a month.
The images: I prompted the model for a hero image. The image came back beautiful and useless. I asked the model to refine it. I changed adjectives. I added detail. The image stayed beautiful and useless. The prompt was the problem. The prompt is a spec. I had been editing the output of a wrong spec for an hour. I deleted the image. I rewrote the prompt. The new image arrived in three minutes.
The failure mode is the same in both cases. I was editing when the spec was wrong. The architect’s discipline says: stop editing. Rewrite the spec. Let the new spec produce a new output. Audit. Then edit if the spec is right and the sentences are not.
This essay is what the architect’s discipline looks like when applied to writing.
The gold standard is the spec, the contract#
The gold standard for any draft is the spec.
The spec is what the work is supposed to do. The spec names the topic. The spec names the audience. The spec names the voice constraints. The spec names the rubric. The spec names what the close must do. The spec is the contract between the writer and the reader. The spec is the contract between the writer and herself.
The spec for this site is twenty-three lines. It names section caps. It names voice constraints. It names what the close must do. It names the household metaphor count. It names the wit budget. Each clause is a binary. The line either passes the spec or it does not. The spec is auditable.
Editing is fine-tuning the output when the spec was right. Revision is going back to the spec and changing it. Most failures are spec failures. Most writers respond to spec failures by editing the output. That does not fix the spec. The failure stays in the next draft. The failure stays in the draft after that.
The architect does not paint a wall before checking whether the wall is in the right place. The writer should not polish a sentence before checking whether the sentence belongs in the essay at all. Most polish is editing the wrong wall.
This is also what makes most writing advice useless. The advice tells writers to polish. The advice does not tell writers to check whether the wall is in the right place first. The check is the real skill. The polish is what comes after.
The discipline is simple. Read the draft. Compare it to the spec. If the draft matches the spec and the spec is right, edit. If the draft does not match the spec, or the spec is wrong, revise.
Revision is the architect’s move. Editing is the painter’s move. Both are skills. Most writers have only one.
This is also what the decision before the sentence means at the architect’s level. The decision is the spec. The sentence follows. If the decision was wrong, no sentence will save it.
Three signs you should revise, not edit, titles, close, polish#
There are three signs a draft needs revision, not editing.
Sign one. The section titles are vague. Vague titles come from a vague spec. If the title is “Some thoughts on X” or “Why X matters,” the spec was vague. Sharpen the title. Watch the section reorganize itself. The new title forces the section to do one thing instead of three.
Example. A section titled “Some thoughts on AI safety” is doing five things. The title cannot decide which. A section titled “The safety page loads faster than the safety team” is doing one. You cannot polish your way from the first title to the second. You have to revise the spec.
Sign two. The close does not land. A close that does not land is a position the writer has not taken. The writer cannot polish the close into landing. The writer has to decide what the position is. The position is a spec change. The close follows from the position.
Example. A close that says “AI is changing how we work, and we need to think carefully about it” is unrevised. The position is missing. A close that says “Burn tokens, not headcount” is revised. The position is named. Same essay. Different spec.
Sign three. You are tempted to polish sentences in the middle section because you want to feel like you are working. The middle section will not change the argument no matter how polished it gets. Polish in the middle is procrastination dressed as craft. The fix is to stop polishing and read the spec.
A fourth sign appears for me. Ambiguity. If a sentence could mean two things, the spec did not pick one of them. The writer can pick one in the spec. Or the writer can accept that the sentence is doing the work of two specs at once. The first move is better. The second move is what most writers do.
When any of these signs appears in a draft, stop editing. Go back to the spec.
What I do, in order, five steps#
The revision process is five steps.
Step one. Re-open the spec. I keep the spec at the top of every working file. When I decide a draft needs revision, I scroll up. I read the spec. I read what the draft was supposed to do. The spec is the question. The draft is the answer. The first thing to do is re-read the question.
Step two. Re-read the draft against the spec. I am not looking for sentence errors. I am looking for spec violations. Did the draft do what the spec said it would do. If not, where did it break.
Step three. Identify which section breaks the spec. The break is not in every section. The break is in one or two. The other sections may be fine. The discipline is to name the broken section before doing any work. Naming the broken section is half the revision. Once the section is named, the fix is procedural. Before the section is named, the fix feels impossible.
Step four. Rewrite the spec for the broken section. The break in the section is a sign that the section’s spec was wrong. I rewrite the spec for that section. The new spec is more specific than the old one. The new spec resolves the ambiguity.
Step five. Let the model audit. I give the new spec to the model. The model rewrites the section against the new spec. The model audits. The model rewrites until the audit passes. I read what passes. The model is faster than I am at finding spec violations. The model is more patient. The model does not get tired on pass forty. I do.
This is the same five steps for an essay as for a hero image. The medium does not matter. The discipline is the same.
I write in modules, so can you#
I write in modules. I think in systems and architecture. Every essay is a set of modules. Each module can be revised without breaking the others.
The opening is a module. The thesis is a module. Each section is a module. The close is a module. The wit moment is a module. The household metaphor is a module. The links are modules.
Modularity is the architecture that makes revision cheap. A revised module costs an hour. A revised monolithic essay costs a week.
Modularity also makes swapping cheap. The same opening with three different middle sections is three different essays. The same middle section with three different opening modules is three different essays for three different audiences. The vertical changes. The system stays.
Modularity is why AI works for the writer who has the discipline. The model can rewrite one module at a time, audited against the spec for that module, without touching the rest of the draft. The architect does the same thing on a building. The painter cannot.
This is why the discipline of the architect is not optional for the writer who wants AI in the room. The model is a contractor. The contractor cannot work with monolithic instructions. The contractor needs modular specs. The writer who gives modular specs gets modular output. The writer who gives monolithic instructions gets monolithic output that breaks at the first revision.
A reader cannot see the modules. The reader sees the essay. The modules are the substrate. The substrate is what makes the work efficient. The substrate is what makes the working folder useful. Every fragment in the working folder is a module that has not yet been placed in an essay.
One example, before and after, the claim, the number, the gap#
Here is a specific revision. Modular, not monolithic.
Before. A draft of the third section of an essay about AI in care work read like this:
AI is changing how we think about care. The model cannot reproduce the work my mother did. Care work is complex and undervalued. The economic data shows that informal caregivers do labor worth trillions. The model cannot count this labor. The forecast does not see it.
The section was six sentences. Each sentence was correct. The section was monolithic. It tried to do five things at once. Name the change. Name the limit. Name the value. Name the data. Name the gap. None of them landed.
I rewrote the spec for that section. The new spec named what the section had to do. State the claim. Ground it in a number. Close with the gap. Three modules. Each module does one thing.
After. The new section reads:
The model cannot reproduce the work my mother did. Informal caregivers in this country perform labor worth more than two trillion dollars a year. The forecast does not see any of it.
Three sentences. Three modules. The claim. The number. The gap.
Each module has a spec. The claim module’s spec is to state the thing the model cannot do. The number module’s spec is to ground the claim in a verifiable figure. The gap module’s spec is to name what the failure costs. Three small specs. Three small outputs. One section that lands.
The new section is shorter. The new section lands. The new section can be lifted and dropped into a different essay because each module is self-contained. The same three modules could anchor a piece about teaching, or about elder care, or about the unpaid work in any household.
I did not edit the old section. I rewrote the spec. The new spec produced a new section. The editing happened after the revision, not before.
This is what modular revision looks like. The spec was rewritten. The output followed. The architect’s move first. The painter’s move second.
What this earns, not painting the wrong wall#
The architect’s discipline says: do not paint a wall before checking whether the wall is in the right place. The writer’s discipline says: do not polish a sentence before checking whether the sentence belongs in the essay at all.
Most polish is editing the wrong wall.
The five-point distillation of this essay is in its companion piece. The companion is the short version, for the reader who wants the discipline without the demonstration. This essay is the demonstration. The companion is the cheat sheet.
Editing belongs to the writer who has gotten the spec right. Revision belongs to the writer who has not. Most writers will spend most of their careers in revision. That is not a failure. That is the work. The architect is the writer who has named the work.
The spec is the gold standard. The output is the consequence. The discipline is what links them.
The spec is open on my desk. The draft is open next to it. The audit is the gate.
Revise.
