Writing rules
Writing mechanics
The rule as we use it, word for word. Every piece on the site is edited against it.
A guide to how a sentence is built, which words and claims it avoids, and how it handles facts and formatting. It sits
on top of the three binding rules in this skill: writing-stages.md (map, rough draft, final), least-first.md (what
goes in) and short-words.md (word length). A project's voice rules, where it has them, sit on top of this.
Most of these rules catch the same thing: writing that reads as padded or machine-made.
Fixing a tell
Cut first. Most tells are additive: a claim of significance the piece hasn't earned, a third triad item, a hedge, a closing paragraph that restates the one before it. If a sentence survives losing its last clause, the clause wasn't needed. Rewrite only when the cut would drop a fact, a mechanism or a contrast the reader needs.
Don't cut into damage. The target is specific, plain, unpadded prose, not a stripped-down minimalism. If a cut drops the one fact that made a claim credible, or leaves a section trailing off where its closing thought used to be, it went too far. Read it back. Does it still sound like the writer, or like the writer with the confidence removed?
Sentences
Short sentences land hard, but only next to longer ones. Use them for conclusions, reveals and anything the reader should feel. Long sentences build up. Short sentences end it. A paragraph of all short sentences has nothing to land against.
Em dashes are a last resort. First check whether a comma, period or colon does the job. An em dash earns its place
only when a comma is too weak and a new sentence would cost something. A pair around an aside (X — Y, Z — verb)
almost always means the sentence should be rebuilt. The test: if taking the em dash out makes you rethink the sentence,
it was doing work. If it only dropped in as a pause, replace it.
Use "is," "are" and "has." Not "serves as," "stands as," "functions as," "represents," "constitutes" or "acts as." Not "features," "offers," "boasts" or "maintains." "The gallery is LAAA's exhibition space" beats "The gallery serves as LAAA's exhibition arm." The fancy verb dresses up a plain claim that didn't need it.
Negate in short, separate sentences. "Not fast. Not cheap." works because each sentence makes its own claim. "It's not just uncomfortable, it's dangerous" is the tell: the two halves lean on each other inside one sentence. If a negation needs "but," "just" or "only" to join its halves, split it. Say what it isn't, then say what it is.
Break the default triad. Three adjectives, three clauses or three examples is the shape unexamined writing falls into. Distrust it. Use two, or four, or one. A triad stays only when the list has exactly three members: coil, Vislon and metal zippers, not "clean, precise, and effective." If the third item restates the first two, or it's the one fact that mattered and the first two are padding, cut the padding and keep the fact.
Don't end on an "-ing" clause that editorializes. "...ensuring durability," "...making it ideal for daily use." If the claim is worth making, make it in its own sentence.
Words
Filler defaults to deletion. Read the sentence without the word. If nothing is lost, it was filler.
- "Actually" and "really" almost never earn it. They borrow emphasis the sentence should carry. "It's actually heavier than it looks" becomes "It's heavier than it looks." Use "actually" only to correct something the reader expected.
- "Real" needs something concrete to point at. "Real-world weight" and "the real cost of a warranty" are fine. "A real problem" and "really comfortable" are not. Cut the word or name the thing.
- Also cut: "genuinely," "honestly," "straightforward," "at the end of the day."
A word that earns its place is rare. If one shows up all over a body of writing, it has become a tic.
Repeat the noun. Say "file" or "strap" twice in a paragraph rather than chase a synonym. People repeat the noun. Only a machine reaches for "the aforementioned carrier." (least-first: one name per thing.)
Shortest word that does the job. See short-words.md.
Claims
Hold the position. "Deserve credit," "worth noting" and "it might be worth mentioning" apologize for positions the writer should just hold. So do "in our opinion," "we think" and "we believe." Say the thing. An honest qualifier is different: "perhaps," "tends to" and "one of the first" are fine when they're true. The tell isn't a soft word. It's a soft word standing in for a position the writer could state.
No unattributed authority. "Experts say," "industry reports suggest" and "widely considered the gold standard" borrow credibility instead of stating the fact. State the fact, or name the source.
Specific over emphatic. When the fact isn't at hand, the pull is toward intensity: "a real problem" instead of naming the problem, "significantly harder" instead of what changes. Don't. Leave the claim out rather than ship the vague version.
Don't claim significance the piece hasn't earned. "Stands as a testament to," "marks a turning point," "underscores its importance." State what happened. The reader decides whether it matters.
Don't guess past what you know. No "while specific details are limited" or "not widely documented" followed by a
guess. If you don't know, leave the claim out. While drafting, mark the gap [NEED: what] (see writing-stages.md),
then fill it or cut it before the final.
No stock formulas. No "Despite its strengths, X faces challenges... but X continues to..." No closing on what a future version "could" do. No press-release lines: "we are committed to...", "every user deserves..."
Facts
Present tense for what is always true. Past tense for what happened.
Instructions say how. When a line tells the reader to check something, it also says how, and what a pass looks like: what to press, run or measure, and what they should see. "Check the stitching" leaves someone with nothing to check. "Pull the strap hard at its base: the stitching shouldn't gap or show light" gives them a test.
Formatting
Applies to any markdown body.
- Sentence case, not Title Case, in every heading. Proper nouns keep their capitals.
- No decorative bold. Bold is for emphasis, used rarely. Not for every instance of a term, not for a "key takeaways" label.
- No inline-header bullet lists. Never
- **Term**: descriptionrepeated down a list. Write prose, or use a table when the reader needs to scan named items. - Straight quotes and apostrophes.
"and', not curly“”’. - No emoji as decoration. Not before headings, not before bullets.
- No thematic break (
---) before every heading, and don't skip a heading level: H2 before H3.
Self-check
Advisory: the checker's --full pass (python3 scripts/check_short_words.py --full) flags these. Each needs a second look, since "actually"
and "real" have valid uses (see Words).
actually · really · real · genuinely · honestly · at the end of the day