Good writing rules

Ported (translated + condensed) from the Russian-language good-writing skill in mikeshu2001/content-factory. The original is the source of truth for Russian-specific grammar rules; this port keeps every transferable rule in English. Attribution: mikeshu2001. The original files are not vendored verbatim because this repo is English-only on disk (docs/developing-ralphy.md).

How to use this skill

This is not a list of bans to tick off. It is a toolset for moments of doubt. The goal: text should explain the way a person explains to a colleague over coffee. Not like a manual, not like marketing, not like an academic paper.

Before editing anything, ask:

• What does this phrase carry for the reader? If nothing — delete it. If it duplicates what was already said — delete it.
• What role does a construction play before you remove it by rule? A formally "banned" construction often holds an important nuance. Understand why it is there first, then decide.
• Does the majority of readers need this fact? A detail useful to 5% of the audience that does not help the rest understand — cut.
• The main test after ANY edit: read the paragraph aloud and ask "would a native speaker say this to a colleague?" If not, the edit is bad even if it is rule-correct. Rewrite the sentence whole; do not patch one word.
• Symptom vs cause. Filler in one phrase usually means the whole paragraph is overloaded. Clean the paragraph, not the sentence. A "not X but Y" contrast usually means you have not found the affirmative form — find it.
• Judge the block, not the sentence. After any edit re-read the whole block. If the edit did not improve the block as a whole, it did not happen.

If a construction is allowed by the rules but sounds clumsy — rewrite it. If it is banned but sounds natural and precise — keep it. Rules are for doubt, not a final judge.

Tone

Calm, informational. No marketing, no exclamation, no attempts to impress. Talk WITH the reader, not AT them. Direct address is fine; chumminess is not. Be direct: if something does not work, say so plainly; if something matters, say it first, not after a wind-up.

Coherence

Every next sentence answers the question that arises after the previous one. The reader must never guess how two thoughts connect.

Connections must be semantic, not verbal. If one sentence logically continues another, do not add "because / therefore / also" — those words are only for places where the link is not obvious without them. Paragraphs must also continue each other; a paragraph change must not feel like a topic jump.

Progressive disclosure. A new concept appears only after the reader has developed a need for it. Do not open with "X is Y". First show the situation, limitation, or question that naturally leads to X — then the term is an answer, not a dictionary entry. After drafting, strip the headings and read the text as one flow: if the paragraph order is unclear without headings, the logic (not the headings) is broken.

Quantitative steps. Do not skip intermediate steps in a process. If a process has stages with counts ("one video = 5 scenes, one poster per scene"), state them explicitly and show how each stage's output feeds the next.

Paragraphs and sentences

Paragraphs are 2-4 sentences, one thought each. Exception: explaining a new concept or a process may take 4-6 sentences — do not shred it into fragments.

Sentences are complete, with a subject and a verb. Every sentence must move the thought forward: if you can delete it and the paragraph's meaning survives, delete it. One block = one job (explain, show an example, instruct, warn) — do not mix jobs inside a block.

Start with the point

No "In today's world..." style intros, no sentences that announce information is coming. If the block heading is "Why the tool fails", the reader knows why they are here — answer the heading immediately. Do not write transition paragraphs between blocks; the heading already gives context.

Verbs, voice, and addressing the reader

• Instructional content (guides, lessons): direct imperative ("Open...", "Upload...").
• Narrative / overview content (essays, reviews, explainers): modality with infinitive ("you can upload", "it is worth adding").
• First-person stories: past-tense narration, no imperative.
• Digests: third person, no reader address.
• Future tense for results of the reader's future actions. The reader has not set anything up yet: "the system WILL categorize", not "the system categorizes". Check every verb, not just the first — tense often breaks mid-sentence.
• Active voice. Every sentence has an actor. "The agent will split the video into parameters", not "the video is split into parameters". Passive as the main predicate is a defect.
• When describing what a service DOES for the user, use modality or future ("will generate", "can create"), not present tense — present reads as marketing copy. Present tense is fine for standing facts (price, supported languages, limits).

Terms and jargon

Explain professional terms on first use, or replace them with plain descriptions. Test: "would someone outside this field understand?" IT jargon ("out of the box", "hardcode", "natively") gets rewritten for a general audience.

Headings

Headings are navigation, not decoration: name the action or the concrete subject, from the reader's perspective ("Which agents to try", not "Products on the market"). One heading = one question. No clickbait add-ons.

Formatting

Lists only where they belong: enumerations, checklists, step sequences. In normal narration, write prose. Bold sparingly — key terms on first mention and real warnings. Code blocks for anything the reader may want to copy (prompts, requests, templates). Number only sequential steps; unordered points get bold lead-ins, not numbers.

Dashes

Use minimally. A dash often hides a skipped thought and makes text choppy. Prefer a verb: "The tool scores calls quickly", not "Call scoring tool — fast and accurate". (In this repo dashes in VO scripts also produce long ElevenLabs pauses — memory elevenlabs-multilingual-v2-em-dash-pacing.)

Anti-patterns and the pre-publication checklist

The full catalog — neuromarkers, hidden neuromarkers, syntactic weight, date pinning, service-description bloat, marketing tone, empty generalities, duplicate blocks, and the final check-question list — lives in references/antipatterns.md. Read it before the final pass on any text.

Pair with /humanizer (Wikipedia "Signs of AI writing" catalog) — humanizer catches English-specific AI tells; this skill owns structure, coherence, and tone.

Russian-specific rules (apply when the copy is Russian)

The original skill carries rules that only make sense in Russian grammar. When writing Russian copy, consult the original source files for: verbal nouns used instead of verbs (nouns ending in -tsiya/-nie/-ka paired with adjectives), short passive participles as predicates (forms like "sobrano/zadan"), bookish copulas ("yavlyaetsya", "predstavlyaet soboy"), bureaucratic adverbials ("po mere", "v ramkakh", "v khode"), aspect/tense agreement inside a paragraph, and the ban on the letter "yo". Source: https://github.com/mikeshu2001/content-factory/blob/main/skills/good-writing/antipatterns.md