Skip to content

introvenk/clear-business-writing-skills / skills/diagnosing-drafts

diagnosing-drafts

Verified

Diagnosing Drafts

Overview

A diagnostic checklist for finding reader-facing problems in an existing draft. Diagnose and suggest: name the problem, offer a concrete fix, let the author decide whether to take it. Source: Bernoff, Writing Without Bullshit, mainly ch. 4–11 and 18–19.

Procedure

  1. Know the job — before editing, establish what stage the draft is at, what the writer is worried about, the deadline, and what kind of edit they want. If it isn't stated and you can't infer it, ask. Don't line-edit a draft whose author asked about structure, or an early draft that will be restructured anyway (ch. 19).

  2. Meaning ratio pass — meaningful words ÷ total words. Under 70% is bullshit territory, 80%+ is readable. Judge contextually, don't compute mechanically. See meaning-ratio.md for the method and a worked example.

  3. Structural diagnoses first (ch. 19). Read the whole piece before marking anything, then check for:

    • No central idea: you can't state the point in one sentence.
    • Buried lead: the point arrives late.
    • No clear advice: it describes but never tells the reader what to do.
    • Pastiche: sections look bolted on or contradict each other.
    • Missing structure: over ~300 words with no headings or lists.

    If any of these apply, fix them and skip line edits.

  4. Technique checks:

    • Passive voice. Zombies test: can you insert "by zombies" after the verb?
    • Jargon.
    • Weasel words and intensifiers ("very", "I think", "it seems").
    • Long sentences: break them up.
    • Walls of paragraphs where a list or table would do. Prose that says "firstly" or "on the other hand" wants to be a list.
    • More than two heading levels.
    • Missing pronouns: bland third-person description instead of "you" (reader) and "I"/"we" (writer). Flag an indeterminate "we": who exactly is speaking?
  5. Number checks (ch. 10):

    • Is the number compared to something familiar or to its history? Does a growth rate state its base?
    • More than three significant digits, or more precision than the source supports? "%" confused with "percentage points"?
    • Is the source and date cited? Is the source credible on method, sample size and age?
    • Correlation presented as cause, with no competing explanation considered?
  6. Reader simulation — after reading, can you say what the point is, why it matters, and what you're supposed to do?

  7. Suggest, don't label — don't just label passive voice, weasels or jargon. Write the rewrite. Always say what to cut. Most good line editing is cutting. Offer a better title and opening if you have one.

  8. Report as reader problems, not style preferences — say "I don't know what you want me to do here," never "I don't like this sentence."

  9. Deliver as a criticism sandwich — open with what works, then summarize the problems and what to fix, and close with a hopeful "this is fixable." Concentrate on the text, not the writer's personal qualities.

Nuances, as tests not caveats

NuanceTest
Weasel words: cut nearly all (ch. 8)Boldness rewrite — restate as boldly as you can. Replace "many/millions/incredible" with a number, a named who, or a specific. Keep a qualifier only for a real comparison ("more", "less") or real intensity ("extremely unstable"). For a generalization with exceptions: if you might be wrong, don't generalize. If exceptions are rare, state it boldly. If they matter, spell them out ("Except for X, …"). Quantify where you can. If the bold version is false, the fix is research, not a hedge
Jargon is audience-dependent (ch. 7)Three-rule test — allowed only if (1) every reader knows it, (2) it has a required legal/technical definition, or (3) it's defined once and reused. Otherwise replace it
Clarity ≠ boring (not from the book)Flatness check — did sentence-length variation and direct address survive editing?

Apply each test to the specific sentence in question. Don't apply it as a blanket rule to the whole document.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall