diff --git a/.cursor/rules/orwell-prose.mdc b/.cursor/rules/orwell-prose.mdc new file mode 100644 index 00000000..845b2f0d --- /dev/null +++ b/.cursor/rules/orwell-prose.mdc @@ -0,0 +1,45 @@ +--- +description: Write all agent output in George Orwell's plain English style +alwaysApply: true +--- + +# Orwell prose for agent output + +Write every agent-facing text in clear, concrete English in the manner of +George Orwell. This covers chat replies, plans, pull request titles and +bodies, commit messages, documentation, and code comments. + +## Rules of style + +1. Prefer the short word to the long one. +2. Cut any word that does no work. +3. Prefer the active voice to the passive. +4. Prefer everyday English to jargon, foreign tags, and vague abstractions. +5. Prefer a fresh, exact phrase to a worn figure of speech. +6. Break any of these rules rather than write something ugly or false. + +## What good output does + +- State the fact first: what changed, what failed, or what the reader must do. +- Use concrete nouns and verbs. Name the file, command, field, or record. +- Keep sentences short. One idea to a sentence when that helps the reader. +- Explain a Flatbread term on first use. Keep exact API, CLI, field, and + record names in code formatting. +- For steps, number them in the order the reader should act. + +## What to avoid + +- Padding and pomp: "leverage", "utilize", "facilitate", "in order to", + "it is worth noting that", "going forward". +- Unexplained house slang such as `epistemic`, `homogeneous refs`, + `retro-link`, `roll up`, `dogfood`, `hero`, `surface`, and `stack`. Use + one only when accuracy demands it, and define it in the same sentence. +- Foggy claims that name no actor and no object. + +## Self-check + +Before you send text, make sure a reader can answer: + +1. What changed? +2. What does each named thing do? +3. What must they do next, and in what order? diff --git a/AGENTS.md b/AGENTS.md index 70f69628..38faa0fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,29 +2,33 @@ ## Plain-language output -Apply this style to every written output: chat responses, plans, PR titles and -descriptions, commit messages, documentation, and code comments. Write for -readers who understand software but are new to Flatbread and the change at -hand. - -- Lead with what changed, why it matters, or what the reader should do. -- Prefer short, concrete sentences with a clear subject and action. -- Explain a Flatbread-specific term the first time it appears. Keep exact API, - CLI, field, and record names in code formatting. +Write every agent-facing text in clear, concrete English in the manner of +George Orwell. This covers chat replies, plans, pull request titles and +bodies, commit messages, documentation, and code comments. Write for readers +who understand software but are new to Flatbread and the change at hand. + +The always-on Cursor rule `.cursor/rules/orwell-prose.mdc` holds the full +style contract. In short: + +- Prefer short words, short sentences, and the active voice. +- Cut any word that does no work. Prefer everyday English to jargon. +- Lead with what changed, why it matters, or what the reader must do. +- Explain a Flatbread term the first time it appears. Keep exact API, CLI, + field, and record names in code formatting. - Describe behavior directly: say what creates, links, stores, reads, or validates what. -- Present multi-step workflows as ordered steps. +- Present multi-step work as ordered steps. Avoid unexplained internal shorthand and abstract labels such as `epistemic`, `homogeneous refs`, `retro-link`, `roll up`, `dogfood`, `hero`, `surface`, and -`stack`. Use one only when technical accuracy requires it, and define it in -the same sentence. +`stack`. Use one only when accuracy demands it, and define it in the same +sentence. -Before delivering written output, confirm that a reader can answer: +Before you send text, make sure a reader can answer: 1. What changed? 2. What does each named thing do? -3. What action should they take, and in what order? +3. What must they do next, and in what order? ## Cursor Cloud specific instructions