no-slop

name

no-slop

description

Mandatory gate before writing or editing any prose in this repo: lesson content, README, ROADMAP, docs, ADRs, commit messages, PR and issue text, code comments. Load this BEFORE drafting, not after. Encodes the house voice and the AI-writing tells that must not ship: padding, puffery, hedging, negative parallelism, rule-of-three, transition stacking, uniform sentence rhythm, vague attribution, and invented specifics. Ships a linter at scripts/slop-lint.js.

No slop

This is a teaching repo. Every sentence either transfers something a reader can use or it is costing them time. AI-generated prose fails that test in a specific, recognisable way: it is fluent, well-organised, and empty. Fluency is not the goal here. Transfer is.

Read this first

Two rules outrank everything below.

1. Never write a fact you have not verified. No invented latency numbers, benchmark figures, dates, version numbers, quotes, or citations. If a number belongs in the text, it comes from a source you actually read, and the source gets named. "Roughly 8ms for a Postgres point read on SSD" needs to be either grounded or reframed as the illustrative estimate it is. Plausible-sounding fabrication is the single worst failure mode available to you here, and it is invisible to every check in this document.

2. If you have nothing to say, do not write. Padding to reach a length, adding a section because the outline has a gap, restating the heading as the first sentence. All of it makes the document worse. Tell the user the section has no content worth writing and why. A short honest document beats a long hollow one, and this repo would rather ship 400 good words than 1,200 smooth ones.

The gate

Before you write, answer these. If you cannot, stop and ask rather than generate.

1. What does the reader know now, and what will they know after? Name the specific delta. "Understand caching" is not a delta. "Know why a 90% hit rate means the database must survive the cache vanishing" is.
2. What is the concrete thing? Every explanation needs at least one of: a worked number, a named system, a specific failure, a real command. Abstraction without an anchor is the texture of slop.
3. What is the cost? This repo's whole thesis is that designs buy something and pay somewhere. If the passage names a benefit and no price, it is incomplete.

The house voice

Derived from the existing content. Match it.

• Second person, present tense, active. "You do not need to cache your data, you need to cache the hot sliver of it."
• Claim first, then the mechanism, then the consequence. No throat-clearing. The first sentence of a lesson is already load-bearing.
• Comma splices are allowed and characteristic. "Caching is not magic, it depends on a property of real workloads." This is deliberate; do not "fix" it.
• Arithmetic shown inline. (0.9 × 0.6) + (0.1 × 8) = 1.34ms. Show the working, then say what it means.
• Dry closers over dramatic ones. "Usually at 3am, usually on a holiday weekend." Understatement, not exclamation.
• No em dashes. The repo uses commas and full stops. Keep it that way.
• Straight quotes and apostrophes only. No curly typography, no emoji.
• Sentence case headings. Proper nouns keep their capitals.
• British-ish spelling is already mixed in (optimise, synchronised). Match the file you are editing rather than converting it.

Banned outright

These have no defensible use here. The linter fails on them.

Category	Examples
Filler openers	"In today's fast-paced world", "In the realm of", "When it comes to", "It's worth noting that", "At the end of the day", "Let's dive in", "Here's the thing", "That's where X comes in", "Enter Redis."
Puffery	"a testament to", "plays a crucial role", "underscores the importance", "rich tapestry", "game-changer", "cutting-edge", "unlock the power of", "seamless", "meticulous", "holistic", "boasts", "vibrant"
Trailing significance	", highlighting the need for...", ", ensuring reliability", ", fostering collaboration". A participial clause bolted on to sound insightful
Weasel attribution	"Studies show", "Experts argue", "It is widely believed", "Industry reports suggest". Name the source or cut the claim
Conclusion formulas	"Despite its strengths, X faces challenges", headings called "Key Takeaways", "Final Thoughts", "Challenges and Future Directions"
Model artifacts	oaicite, contentReference, [cite: 1], turn0search0, "As of my knowledge cutoff", "[insert example]"

Rationed, not banned

One is rhetoric. Four is a tic. The linter caps these per file.

• Negative parallelism: "not just X, but Y", "it's not X, it's Y", and the reversed form "building the intuition, not memorising the diagrams". The single most recognisable LLM cadence, in all three of its shapes. One per file, maximum. The landing-page hero shipped with two of them inside sixty words, which is what convergence looks like in practice.
• Formal transition openers: "Moreover", "Furthermore", "Additionally", "Ultimately". Two per file. If a paragraph needs "Furthermore" to connect to the last one, the order is wrong, not the connective.
• Rule of three: "fast, reliable, and scalable". Triads create a false sense of completeness. Use two items, or four, or the actual number.
• Watch-list vocabulary: delve, myriad, plethora, realm, ecosystem, intricate, robust, comprehensive, utilise, facilitate, empower, foster, streamline, bolster, crucial, pivotal, vital. Capped at 6 per 1,000 words. ("Highest leverage" as a noun is fine and precise; "leveraging X" is not.)
• Copula avoidance: "serves as", "stands as", "functions as". Usually "is".

What the linter cannot see

These are yours to check by hand, and they matter more than everything above.

• The deletion test. Remove each sentence. If the paragraph loses no information, the sentence was filler. More than a third failing means rewrite, not edit.
• The restatement test. After each paragraph, name one concrete fact a reader now has. If you cannot, the paragraph is decorative.
• Hedging. "can be", "may sometimes", "generally tends to" stacked in one sentence is a refusal to commit. Technical writing needs conditions, not cushions. State the condition: "under a Zipfian access pattern", not "generally".
• False balance. Presenting a settled trade-off as an even split because even-handedness sounds safe. If one option is usually right, say so and say when it is not.
• Paragraph shape uniformity. Topic sentence, three supporting sentences, wrap-up, repeated down the page. Real explanation has irregular paragraphs because ideas are irregular.
• Sentence rhythm. If every sentence lands between 15 and 25 words, the prose drones. Vary it deliberately. Short one lands hard.
• Structure inflation. Bullets that were a sentence. A table with two rows. A heading over one paragraph. Lists are for genuinely parallel items.

Workflow

Writing new prose

1. Answer the three gate questions.
2. Draft. Prefer under-writing; you can always add.
3. Run the deletion and restatement tests on your own draft, and cut.
4. Run the linter.
5. Fix every FAIL. Judge each advisory yourself: proper nouns, glossaries and dense technical prose trip them legitimately.

Editing existing prose. Same, plus one addition: preserve the author's voice. This repo already sounds like a person. Do not smooth it into house-style AI prose while "cleaning" it. Comma splices, sentence fragments, and dry asides stay.

npm run lint:prose

Useful flags: --json for machine output, --strict to fail on advisories too.

Copy is not only in markdown. The headline, section blurbs, button labels and widget notes are string literals in course/assets/js. The linter reads those too, pulling out long string literals and visible HTML text and running the phrase rules over them. Density metrics are skipped there, because an extracted fragment has no paragraph shape to measure. If you add a new place that holds reader-facing copy, add it to the lint:prose script.

A clean linter run is a floor, not a pass. It proves you avoided the known phrasings. It cannot tell you whether the writing teaches anything.

When to break a rule

Rules here serve clarity, and occasionally they conflict with it.

• Quoting a source that uses banned phrasing. Quote it accurately.
• A proper name in Title Case is a proper name.
• Glossaries and reference pages are legitimately bold-dense and list-shaped.
• The trade-off boxes (::: tradeoff) exist to name costs; contrast structures are the point there.

Break the rule deliberately, and say why in the PR description. Do not break it by accident and rationalise afterwards.

Reference

references/tells.md holds the full catalogue of AI-writing tells, with sources and measured thresholds, for when you need to justify a call or extend the linter.