Prose

Prose (Universal)

The writing around code is read by someone who is trying to do a task. A teammate setting the project up, a reviewer deciding whether to approve, a person reading a commit message six months from now to find out why a line exists. Prose earns its place by making that task faster.

This file is the only place in the pack that defines prose rules. Other files point here rather than restating them. See Authority.

Non-goal: passing an AI detector. Detector scores are not a quality measure, and writing to beat one produces worse docs. Do not introduce typos, inconsistent formatting, or deliberately uneven structure to seem human.

1. Words

Cut on sight:

Adverbs get a higher bar than other words. Most that survive a first draft are describing something the verb should have carried. significantly improves is a claim without a number. cuts p99 from 400ms to 90ms is the sentence you meant.

Named things beat categories. Redis over a caching layer, bun test over the test suite, src/auth/session.ts over the relevant module.

2. Punctuation

• No em dash as sentence punctuation. Use a period, comma, colon, or parentheses. Hyphens inside compound words are fine.
• No exclamation marks in docs, commits, or error copy.
• Bold is for one thing per section, at most. Bolding five phrases on a screen leaves nothing emphasized.
• Straight quotes in code and CLI output. Typographic quotes are a product-UI decision, covered in prompts/scaffolds/Website-Design.md.

3. Structural patterns

These are the tells that survive a word-level cleanup, and the reason a doc still reads as generated after every banned adjective is gone.

Binary contrast. Setting up a thing only to negate it in the same breath.

The language changes per project, the definition of good code does not.

Write the half that carries information: Every template starts with Clean-Code because the standards outlive the stack.

Negative listing. Defining something by what it is not, when nobody suspected it was.

This is not a framework. It is not a linter. It is a set of files.

Say what it is once.

Dramatic fragmentation. Sentence fragments deployed for rhythm.

Load one file at a time. That is the rule. Nothing else matters as much.

One complete sentence does the same work.

Rhetorical setup. Announcing a count or a question, then answering yourself.

Two things go wrong when you build with an agent.

Go straight to the first thing. Numbered headings already tell the reader there are two.

False agency. Giving inanimate subjects intent: the config wants, the test is trying to tell you, your code deserves. Name the actual actor.

Narrator distance. Describing the reader's inner life from outside. You might be wondering, by now you have probably noticed, nothing is technically broken, so nothing gets fixed. State the condition instead.

Passive voice hiding the actor. The migration is run automatically leaves out what runs it. Only use passive when the actor genuinely does not matter.

4. Rhythm tics

• Always three. Three examples, three bullets, three clauses, on every list. Real sets are rarely all size three. Use the number of items that exist.
• Punchy closer. Ending a section with a short declarative for effect: Delete when in doubt. That is deliberate. Ship it. Cut them, or fold the content into the paragraph above.
• Forced parallelism. Bending every bullet into the same grammatical shape when the items are not parallel in meaning.
• Uniform sentence length. Twelve sentences in a row at fifteen words each reads flat no matter how good the words are. Vary length because the ideas vary in size, not to perform variation.

5. Do not overcorrect

The rules above cost more than they save when applied blindly.

• A contrast that carries real information is a good sentence. The pattern to cut is the decorative kind that adds nothing.
• A list of three is fine when there are three things.
• Precise technical terms are not jargon. idempotent, backpressure, and nullable are the shortest correct words available.
• Repeating a term is better than reaching for a synonym. Session on every line beats alternating with token, handle, and context.
• Never change a factual claim to improve a sentence. Accuracy outranks every rule here.

6. By document type

7. Checklist

• No filler adjectives, verb inflation, or discourse glue
• Every adverb either carries a number or is gone
• No em dash used as punctuation
• No binary contrast, negative listing, or rhetorical setup
• No fragments written for rhythm, no punchy section closers
• List lengths match the number of real items
• Claims name a file, command, or number the reader can check
• Nothing restates what a linked file already shows
• No detector-driven edits, no deliberate inconsistency

Authority

Prose rules live here. These files point at this one:

On naming inside code, standards/Clean-Code/ wins (04, 06, 20, 30, 36, 39). This file governs sentences, not identifiers.