From 4ca9ae1733dfb664491d8a51f799f99c5621f7ba Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 27 Jul 2026 22:50:23 +0000 Subject: [PATCH] docs(agents): require Orwell plain English for all agent output Add an always-on Cursor rule so every agent reply, plan, commit message, pull request text, doc edit, and code comment uses clear concrete English in the manner of George Orwell. Point AGENTS.md at that rule so the same contract applies repo-wide. Change-Id: I862937326f3fcbe3f619a3ae54c68124cc677e7f --- .cursor/rules/orwell-prose.mdc | 45 ++++++++++++++++++++++++++++++++++ AGENTS.md | 32 +++++++++++++----------- 2 files changed, 63 insertions(+), 14 deletions(-) create mode 100644 .cursor/rules/orwell-prose.mdc 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