deslop

name

deslop

description

Revise writing so it is easy to understand, specific, and useful. Use for documentation, design documents, plans, proposals, launch notes, reviews, PR descriptions, status updates, and multi-paragraph messages. Remove vague nouns and measures, canned phrases, sentences with too many ideas, empty claims, repeated writing patterns, and needless formatting. Preserve facts, uncertainty, technical terms, and the author's voice. Skip tiny mechanical edits.

Deslop

Goal

Help the reader understand the writing on the first reading.

Deslop is a set of rules for writing clearly. It does not decide the output format. Let the task determine the format: a rewrite, review comments, proposed edits, a patch plan, release notes, a PR description, or another format. Apply these rules inside that format.

Slop is writing that looks finished but makes people find the point, guess what a noun refers to, or trust a claim that has no support. Human writing and AI-written text can both have these faults.

The requester may know more than the people who read the text later. Include the names, definitions, decisions, and reasons that later readers need, even when the requester already knows them.

A file or message may be read many times. Spend time making the text clear once. Respect the time of everyone who will read it.

Aim for common words and simple sentence structures like those used in Simple English Wikipedia. Plain English can be warm, detailed, and specific. It may need more words than compressed or abstract prose. Keep technical terms when common words would change the meaning. Define them when later readers may not know them.

Plain English does not mean removing useful technical names. Keep names such as load_config(), manifest.json, CLI flags, HTTP status names, database table names, product names, and team names when they help readers point to the same thing.

Research when it helps

For a long document or a rewrite that depends on internal context, use $slack and $notion search when they are available. Search for:

• the names, facts, decisions, owners, and dates that the text needs;
• recent writing by the author or for the same readers;
• examples that those readers found clear or hard to understand; and
• recent discussion of "slop", "AI slop", or repeated words and sentence forms in AI-written text.

Use the results to add missing names, facts, decisions, owners, and dates; match the level of detail expected by the readers; and avoid repeated canned writing patterns.

Use web search for current public examples and plain-language guidance. Keep internal examples private. Do not put private drafts, customer data, or other internal details in a web query. Carry over the writing lesson, not the source text.

When the text depends on a repository, inspect the relevant files, tests, error messages, and nearby documentation before rewriting claims about behavior. Do not infer behavior from a file name alone.

Skip research for a small edit when it would not change the result. If a search tool is unavailable, continue with the text and the rules below. Mention the missing context only when it limits the rewrite.

Workflow

1. Identify the people who will read the text now and later. Determine what they know and what they need to understand or do.
2. Find the main point: the change, result, decision, request, or conclusion.
3. Find the facts and reasons that support the point. Mark unknowns as unknown.
4. Put the point first. For a decision or status update, use the parts of this order that the reader needs: point, evidence, reason or tradeoff, next action. Do not force all four parts into every paragraph.
5. Rewrite with the rules below. Preserve the author's facts and useful voice.
6. Check each sentence in its nearby context, then read the whole draft once.
7. For a long draft, count content words and short phrases. Review the most common words and phrases in context. Remove repeated ideas. Replace canned phrases with direct statements. When a general word has several meanings, use a specific word for each meaning.

Write in plain English

• Use common words when they preserve the meaning.
• Give each sentence one main idea. Split sentences joined by several uses of and, but, while, or which, or sentences that carry several conditions or exceptions.
• Name the subject and the action. Use active voice when the actor matters.
• Keep this, it, they, and similar words close to the noun they refer to.
• Prefer a verb to a phrase built around an action noun. Write "we decided" instead of "a decision was made" when we is the actor.
• The same rule applies to technical writing. Write "the server returns 404" instead of "the server is responsible for the handling of not-found cases."
• Break up long strings of nouns. State how the nouns relate to one another.
• Replace vague measures such as significant, substantial, high, low, fast, or large with a number, comparison, or named condition. If no measure exists, say what was observed.
• Add words when they remove doubt. Short writing is not the goal.
• Choose the level of detail required for the reader's task. Use precise names for included details, but do not include details that do not help the reader understand or evaluate the result.
• Keep related sentences together. A sentence should make sense on its own or from the few sentences around it.
• Preserve warmth, humor, directness, and useful rough edges. Do not make every author sound the same.

Make nouns refer to something specific

A noun should identify something specific. Prefer a proper name or technical name.

When words such as the service, this change, the result, or the boundary depend on nearby text, state what they refer to in the same paragraph or the paragraph immediately before it. Otherwise, repeat the proper or technical name, or define the noun again. Do not make people search farther back.

When the text returns to a person, file, function, system, decision, or behavior, reuse its name. Do not substitute a synonym or metaphor merely to vary the writing.

Catch-all words such as seam, gate, lane, cut, slice, surface, shape, space, path, flow, boundary, and narrow often name several unrelated things. Keep one only when it names a specific thing. For each use, ask:

1. What code, data, decision, or work does this word name?
2. Would two people point to the same thing?
3. If the word is removed, does the sentence lose any meaning?

If the answer is unclear, use the name or remove the word. These words are warnings, not banned words. Security boundary and filesystem path can be specific terms when they name a defined concept. Do not keep a word only because it is common jargon.

Remove canned writing

• Empty claims of importance, quality, or progress. Say why something matters.
• Stock words such as crucial, pivotal, robust, meaningful, delve, landscape, underscore, foster, enhance, and tapestry when they add tone but no information.
• Canned contrasts such as "not X, but Y", "not only X, but also Y", or "treat X as Y, not Z" when the reader did not hold the claimed mistaken view. State the claim or instruction directly.
• Canned openers and summaries such as "It is important to note", "In summary", or "Overall" when they delay or repeat the point.
• Repeated groups of three that add length without adding information.
• Claims attributed to "experts", "stakeholders", "research", or "the industry". Name the source or state that the source is unknown.
• Generic praise, urgency, and process history that the reader does not need.
• Metaphors or personification that replace a file, behavior, state, or decision. A joke can follow a clear statement; it cannot replace the statement.
• Unexplained references to a prompt, conversation, tool call, or investigation that later readers cannot see. State or link the information they need.
• A final clause that only adds importance, such as "highlighting its value" or "ensuring future success".
• Headings, bold labels, bullets, tables, and summaries that do not help the reader find or use information.
• A conclusion that repeats the point and a closing offer to do more work when there is no useful next action to name.

A deliberate contrast or useful list may remain. Keep it only when it helps people understand the text.

Use evidence and reasons

• Replace praise and reassurance with evidence or a direct reason.
• Separate evidence from interpretation. State what happened, then say what you think it means.
• Explain why a log, metric, example, or source supports the point. Do not assume people know the investigation that produced it.
• For a decision, name the real tradeoff or value when it helps the reader understand the choice.
• Do not invent evidence, dates, metrics, owners, decisions, or certainty.

Examples

Canned contrast and unclear measure:

Before: For a long draft, count content words and short phrases. Treat a high count as a clue, not an error. Remove repeated ideas. Keep a name unchanged when it refers to the same thing. Replace a general word that has several meanings with a specific word for each meaning.

After: For a long draft, count content words and short phrases. Review the ones that appear most often. Remove ideas stated more than once. Keep a name unchanged when it refers to the same thing. If a general word has several meanings, use a specific word for each meaning.

Vague nouns:

Before: The next useful seam is a narrow gate in load_config() for configs without version.

After: load_config() should reject a configuration when version is missing.

Vague measures and buried comparison:

Before: The new retry policy delivered a substantial reliability improvement during the overnight replay, taking the worker from a somewhat unstable 37 failed jobs out of 500 under the old retry policy to a much healthier 4 failed jobs out of 500 under the new retry policy.

After: In the overnight replay, the new retry policy reduced failed jobs from 37 of 500 to 4 of 500.

Missing context recovered from a design record:

Draft: We chose the second option because it fixes yesterday's issue.

Relevant source material: Option 2 changes write_manifest() to write manifest.json to a temporary file and rename it atomically. During yesterday's incident, deploy-worker read manifest.json while it was only partly written. The atomic rename prevents partial reads.

Revised: write_manifest() will write manifest.json to a temporary file, then rename it atomically. This prevents deploy-worker from reading a partially written manifest.

Code comment:

Before: # Ensure robust handling of invalid configs

After: # Reject configs without version before reading feature flags.

Metaphor and personification:

Before: report-menu wants a different contract, not just a different skin. Unlike report, report-menu loads a saved query instead of accepting command-line flags.

After: report accepts command-line flags. report-menu loads a saved query.

Several conditions in one sentence:

Before: When a retry arrives while the worker is shutting down, and if no newer attempt has started, the handler can reuse the result provided that the lease is still valid.

After: Suppose a retry arrives while the worker is shutting down. The handler may reuse the result if the lease is still valid. It must not reuse the result if a newer attempt has started.

Polish without evidence:

Before: By preventing a retry from writing the same row twice, this change creates a robust foundation for future reliability.

After: This change prevents a retry from writing the same row twice.

Final check

When the answer to a check is no, apply the matching rule above before returning the text.

• Does the text depend on information outside the file or message? State or link the information that later readers need.
• What does each noun refer to? If the answer is not in the same paragraph or the paragraph immediately before it, repeat the proper or technical name, or define the noun again.
• Who performs each action?
• Does each sentence have one main idea?
• Are conditions and exceptions easy to follow?
• Does each measure use a number, comparison, or named condition?
• Is each claim supported, marked as an inference, or marked as unknown?
• Does each heading, list, table, or bold phrase help the reader?
• Did the rewrite keep the author's meaning, uncertainty, and voice?
• Could a sentence appear unchanged in a memo about a different project? If so, make it specific or remove it.