Writing Style

This guide covers everything you write for me: plan documents, research notes, issue and PR descriptions, console output, review findings, summaries, and questions. Other documents say which sections a plan or a PR should have. This one says how the sentences should read.

The test

Write for a colleague who was not in the session and is reading cold. They should understand what you wrote in one pass, without a glossary and without opening the codebase. If a sentence would make that person stop and decode it, rewrite it.

The rules

Write in plain English, in full sentences. Say what is happening the way you would explain it out loud. Use bullets only for things that are actually a list, such as files, commands, or findings. Never turn prose into fragments or arrow chains. Write "the client asks for an upload URL, sends the file, then confirms," not "presign -> PUT -> confirm."

Use technical terms when they are the real name of something. If the code calls it StepContext or merged_metadata(), use that name. Do not swap it for a friendlier word, because then I can no longer find it in the code. If a term is not common, say what it means the first time you use it. Never invent jargon of your own.

Introduce things before you refer to them. The first mention of a component, a finding, or a phase says in a few words what it is. Do not assume I remember a label like "F3" or "the union" from earlier in the session.

Lead with the point. Every document and every section opens with its conclusion in plain prose. Detail follows for the reader who wants it. A heading is followed by at least one sentence, never straight by a list.

Keep paragraphs to one idea. One to four sentences each. If a paragraph is carrying three decisions, split it. When something is too long, cut detail that does not change what I know or need to do next. Do not shorten by squeezing more facts into fewer words; that is how dense, unreadable paragraphs happen. Keep parentheses for asides. If a parenthetical contains something I need, give it its own sentence. File references like file:line support a sentence; the sentence must still make sense with them removed.

Asking me a question

When you ask me to decide something, I should be able to answer from the message alone. Before you list the options, explain in plain terms what the problem is, why it matters, and what each choice gives up. Then give the options. Options written in shorthand like "fail-open" or "polymorphic," with no explanation of the problem underneath, force me to ask you to explain before I can answer.