# Writing Review > Use before sending prose that has to persuade, explain, or be acted on — a report, proposal, email, summary, design doc, or manuscript section. Checks whether the argument holds and whether the sentences carry it: an unstated point, sections in an order nobody can follow, generalizations with no evidence under them, abstraction where a concrete noun belongs, and clutter that survived the first draft. Triggered by: finishing a draft, "does this read well", "can you review this writing", sending something to a reader who can stop reading. - Skill: `michaelwjohnson/writing-review` (Agent Skill) - Install (CLI): `npx skillmds@latest add michaelwjohnson/writing-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/michaelwjohnson/writing-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: michaelwjohnson (https://skillmd.com/u/michaelwjohnson) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/michaelwjohnson/writing-review --- # Writing Review ## Core Principle Two things can be wrong with a piece of writing, and they fail independently. **The argument can fail.** No point, or a point nobody can find. Sections in an order that hides the logic. Assertions with nothing under them. **The sentences can fail.** Abstraction where a concrete noun belongs. Twelve words doing four words' work. A voice nobody would use out loud. A draft can be immaculate at sentence level and say nothing. It can have a real argument buried in prose no one will finish. Check both, separately, in that order — fixing sentences in a section you are about to cut is wasted work. --- ## Level 1 — The Argument ### Purpose > "A thesis and direction are clear. The writing is addressed to a well-defined > audience." One point, not three. Name it in a single sentence. If you cannot, the draft is still thinking rather than telling. Then name the reader. Not "people" — the actual person who will act on this, and what they already know. Purpose without an audience produces writing that is technically correct and lands nowhere. **Test:** what is the one sentence a reader should be able to repeat afterwards? Is it in the document, or only in your head? ### Organization > "Ideas and support are developed one at a time systematically and logically." One idea at a time, in an order the reader can predict. Ascending, descending, chronological, or parallel — any of those work; no discernible pattern does not. **Test:** read only the headings and first sentences. Does the argument still follow? If the order could be shuffled without loss, there was no order. ### Coherence > "Conceptual links are provided between individual elements." The joins between ideas, stated rather than implied. Key terms repeated instead of elegantly varied — a reader tracking an argument needs the same word for the same thing. Summary where a section turns. **Test:** at each section break, can the reader say why this follows that? If the link lives only in your head, the document has a gap the reader will fall into. **Not this:** connective words sprinkled as decoration. "Furthermore" between two unrelated points is a lie about a relationship. ### Support > "All generalizations and conclusions are justified by logically presented > evidence." Every generalization carries its evidence, and the evidence is *interpreted* — quotations and figures do not explain themselves. A number dropped into a paragraph without a sentence saying what it means is decoration. **Test:** underline every claim. For each, point at the thing that justifies it. Unjustified claims either get evidence or get softened to the honest version. --- ## Level 2 — The Sentences ### Clarity > "Diction and syntax are precise; the writer has considered the reader's > understanding." - **Concrete over abstract.** Name the thing. Concept nouns hide who did what — replace them with people and verbs. - **Active over passive.** "The committee rejected it" beats "it was rejected." Passive voice hides the actor, which is sometimes the point and usually a bug. - **Short sentences.** Use periods freely. A long sentence is usually two. - **Subject-verb-object.** Deviate deliberately, not by accident. ### Clutter > "Vigorous writing is concise." — Strunk, via Zinsser Most first drafts are a third too long. Cut: | Cut | Why | |---|---| | Qualifiers — *rather, quite, sort of, a bit* | They weaken the sentence and buy nothing | | Adverbs propping up weak verbs | Find the verb that does not need help | | Decorative adjectives | Keep the ones carrying information | | Phrases that restate the previous sentence | The reader got it | **Test:** read it aloud. The sentences you stumble over are the ones to rewrite — not because reading aloud is a rule, but because stumbling locates the problem faster than staring does. ### Voice > "Never say anything in writing that you wouldn't say in conversation." — > Zinsser Write as you would explain it to a competent colleague. Jargon and clichés are both substitutes for having decided what you mean. This does not license sloppiness. It rules out the register people adopt when they are performing authority rather than exercising it. ### Paragraphs, Lead, Ending - **Paragraphs** short enough to look inviting. Each one advances the argument. - **The lead** earns the second sentence. Not throat-clearing, not a summary of what you are about to say. - **The ending** stops. It does not recap what the reader just read. The best endings surprise slightly and feel inevitable anyway. --- ## Insight > "The writer has found creative ways to integrate, synthesize, and interpret > challenging ideas." The one principle that cannot be reduced to a checklist. Synthesis — the sources combined into something none of them said — is what separates a competent draft from one worth reading. **Test:** does the document contain a sentence that is yours? If every claim could be traced to a source and nothing connects them, it is a literature review wearing an argument's clothes. --- ## What This Does Not Do Two adjacent checks, deliberately kept separate: | Question | Skill | |---|---| | Does every element earn its place? | `occams-razor` | | Is any of this false? | `check-claims` | The overlaps are real and the boundaries matter: - **Clutter vs the razor.** This skill cuts words that do not earn their place. The razor cuts *sections, comparisons and components* that do not. Different altitude, same instinct. - **Support vs check-claims.** Support asks whether a claim has evidence under it. `check-claims` asks whether that evidence is *true*. Well-supported and wrong is a real state. Running all three on one document is reasonable. Folding them into one skill is not — it would be one check answering three questions. --- ## Order 1. **Purpose.** If the point is unclear, nothing below matters. 2. **Organization and Support.** Structural fixes move whole paragraphs. 3. **Sentences.** Last, because you are polishing text that will survive. Polishing before the argument settles is the most common way to waste an afternoon on a draft you then restructure. --- ## Self-Check | Finding | Status | |---|---| | The one-sentence point is in the document | Purpose holds | | Headings alone carry the argument | Organization holds | | Every claim has evidence you can point at | Support holds | | Nothing survives being read aloud unchanged | Rewrite those sentences | | Nothing in it is yours | Stop. This is assembled, not written. | --- ## Sources - "The Six Principles of Good Writing," Campus Writing Program — purpose, organization, coherence, support, clarity, insight. - Jeff Zych, "Writing" — purposeful, clear, genuine, and the mechanics, drawing on William Zinsser's *On Writing Well*. The first is a rubric for argument; the second is a craft doctrine for holding a reader. They agree on purpose and clarity, which is why those two carry the most weight here.