LLM Writing

Load /creative-writing-skills:intent-modeling if it isn't already loaded, and /creative-writing-skills:information-hierarchy when the piece grows beyond a short answer.

Write for the Reader

Text that outlives the conversation (files, prompts, docs, commit messages, PRs) is read by someone without it: a cold agent, a teammate, or the person who asked, after they've forgotten it. Before writing, decide who reads it, what they know when they start, and what they came for, then lead with what serves them and cut what only serves you. Break the piece into beats, each one move in the reader's journey. Check the source material it rests on.

Draft the whole piece where you can revise it before it reaches its reader: the file itself, or a scratch file. Text sent straight into a chat, a PR or a commit gets no revision. Revise from the whole piece down to the words: is each part correct, does it follow from what came before, and does the reader need it? After a local change, reread the beat around it.

Choose Words

• Use the short, everyday word: "use", not "utilize"; "help", not "facilitate". A long word has to buy its length with precision.
• The project's own names are the word list. Write the real name as the project spells it, whether a symbol, a file, a flag, a character, or an invented term, not a synonym or a description of it, and call each thing by one name everywhere.
• Don't invent jargon. Use the words the reader would say out loud ("move", "delete", "a budget that only decreases"), not a coined metaphor ("evacuate", "ratchet"). A named pattern is fine when the text says what it means the first time.
• Be specific over sterile: not "schema changes can cause issues" but "a column rename fails the build".
• Vary the rhythm. Short sentences land a point; longer ones carry a fact with its condition or consequence. Split the sentence that carries two thoughts; keep the long one that carries one.
• Leave no sentence open to two readings: "only" and "not" next to the word they change, every "it" and "this" pointing at one noun, no noun strings. The cases and a before/after are in resources/word-choice.md.