Agent Writing Guidelines

View Markdown

Review text against every rule below. Flag each issue with its location and a concrete fix. Preserve the meaning; do not invent facts to satisfy a rule.

Rules

Rewriting & fidelity

• Preserve every requirement: keep concrete names, examples, measurements, constraints, and terminology from the source
• Required work stays required; optional suggestions stay optional. Do not turn a suggestion into a commitment
• No added scope: do not invent requirements, edge cases, implementation details, or plans to make a rewrite feel complete
• Preserve relationships: keep the trigger, action, and consequence explicit. Do not reduce a conditional rule to an isolated fact
• Preserve state boundaries: distinguish current from cumulative values, temporary from permanent changes, and what resets from what persists
• Resolve ambiguity only when the source makes the intended meaning evident. Do not guess at missing rules
• Keep named methods when replacing them would weaken a requirement. Leave passages designated as verbatim unchanged
• Fidelity before length: never remove, merge, or rename distinct requirements to meet a word target

Voice & tone

• Active voice: “queries are validated” becomes “the compiler validates queries”. Passive is fine when the actor is unknown or irrelevant
• Direct address: you, never the user or one can
• Imperative for steps: “Click Add Project”, not “You will need to click Add Project”
• Aim for sentences under 20 words; keep related clauses together when splitting would obscure the meaning
• Contractions encouraged: “you’ll”, “it’s”
• Present tense unless describing past events or future behavior
• Limit “we” to deliberate actions by your organization, never as a stand-in for “you”
• No rhetorical questions, flattery, or chatbot pleasantries: cut “Great question!”, “Of course!”, “I hope this helps!”
• Second-read test: read once at speech pace. If you need another pass, name the subject, action, and consequence

Word choice

• Plain words: “utilize” becomes “use”, “facilitate” becomes “help”, “in the event that” becomes “if”
• Literal phrasing: “a dial worth turning” becomes “a parameter worth varying”. Cut metaphor or flourish that adds no meaning
• Concrete actions: “the database stays close at hand” says nothing about its behavior. Name the mechanism or measurable result
• Specific claims: “types that follow your schema” becomes “a column rename fails the build”, if that is what happens
• Literal verbs: replace “lands”, “carries”, “hits”, or “rides along” with the actual step, such as “returns”, “stores”, or “calls”
• Consistent terms: pick one name for each thing. Do not cycle through synonyms for variety
• Reader vocabulary: replace specialist terms only when familiar words preserve the meaning
• Useful adjectives: keep words that specify an observable result. “Raised edge” gives direction; “stylish finish” does not
• Adverbs: cut them or state the result. “Significantly improves” needs a measured change, not a stronger adjective
• Direct statements: “serves as” becomes “is”, “boasts” becomes “has”. Replace “Not just X, but Y” with the point itself

Banned words

• easy, simple, quick for reader actions: replace with a concrete description, such as “one command” or “default settings”
• very, just, really, simply: filler; cut or rewrite
• Inflated vocabulary: cut or replace “crucial”, “delve”, “enduring”, “enhance”, “garner”, “interplay”, “intricate”, “pivotal”, “testament”, “underscore”, “vibrant”
• Abstract metaphor nouns: “substrate”, “wedge”, “vector”, “locus”, “vantage”, “nexus”, “bedrock”, “modality”, “paradigm”. Use the concrete thing or action
• Figurative technical terms: “primitive”, “harness”, “surface”, “scaffolding”, “ratchet”. Keep literal technical meanings; replace metaphors
• Stock metaphors: “landscape”, “tapestry”, “north star”, “flywheel”. Name the subject, goal, or process
• Inflated descriptions: “gold-plating” becomes “more than the job needs”, “evacuate” becomes “move out”, “endgame” becomes “the last phase”

Concision

• Use ASD-STE100 Simplified Technical English for technical prose
• Earn every detail: cut repetition and incidental detail that do not change understanding or action. Keep explicit source requirements when rewriting
• One idea per sentence: split dense sentences or drop clauses that make the reader backtrack
• Filler phrases: “in order to” becomes “to”, “due to the fact that” becomes “because”. Delete “it is important to note that”
• Excessive hedging: “could potentially possibly” becomes “may”. Keep uncertainty when the evidence requires it
• Over-compression: keep articles and verbs. “Parser rejects bad date → exit 2, no write” becomes “The parser rejects a bad date, exits with code 2, and writes nothing”
• Generic conclusions: cut “The future looks bright”. End with a specific fact, decision, or next step

Claims & evidence

• Weasel words: replace “significantly”, “many”, “often”, “typically”, or “generally” with a specific claim you can support
• Vague quantifiers: replace “near-zero”, “sub-second”, or “most requests” with a cited figure. If no figure exists, narrow or remove the claim
• Vague attributions: “experts believe” and “industry reports suggest” need a named source. Cite it or cut the attribution
• Unsupported implications: “highlighting…”, “ensuring…”, “reflecting…”, “showcasing…”, “fostering…”. State the consequence and its evidence, or delete
• Interchangeable copy: if a sentence could describe another project unchanged, name what distinguishes this one or cut it

AI-generated tells (flag these)

• Summary-style transitions: cut “With this setup complete…” or “Now that we’ve explored…”. Start with the next point
• Stop-start sentences: do not split one dependent idea into fragments. “Previously this was manual. Now it’s automatic” becomes “The scheduler now runs the task automatically”
• Spec-sheet voice: replace “is configurable” with what you can configure and how
• Disconnected paragraphs: connect the opening sentence to the preceding idea when it continues that idea. Do not force a transition for a new subject
• Personified artifacts: “hand the browser a URL” becomes “the browser fetches the URL”
• Template framing: cut “The question most teams face is whether…”. State the choice specific to the subject
• Forced groups of three: use the number of items the subject requires
• False ranges: use “from X to Y” only for a meaningful range. Otherwise, list the topics
• Decorative transitions: cut “additionally” when the next sentence already makes the connection clear

Tone, by content type

• Tutorial: warm, encouraging, predictable; do not hide prerequisites or failure conditions
• How-to: terse and direct; the reader is mid-task
• Reference: neutral, exhaustive, quotable
• Conceptual: explain so the reader can teach it back; use examples or analogies that clarify a mechanism
• Troubleshooting: acknowledge the problem, then explain the fix; empathetic, not apologetic
• Feedback: state what is wrong, when it happens, and the expected result. Use natural paragraphs, not report language; clear fragments or shorthand are fine

Headings & structure

• Match the requested format: do not add headings, lists, summaries, or commentary to a plain-paragraph rewrite
• Let each thought start naturally; do not impose a recurring opener or fixed structure
• Sentence case for headings: “Configure environment variables”, not “Configure Environment Variables”
• Descriptive headings: “Caveats when self-hosting”, not “Caveats”. The heading should predict the section’s content
• Open explanatory prose with a short summary; start each major section with its main point
• Define unfamiliar terms on first use. Spell out acronyms, such as “Content Security Policy”, before using “CSP”
• Keep paragraphs to 2 to 4 sentences; split anything longer or covering two ideas. Shorter paragraphs are fine for emphasis

Lists

• Convert 3 or more list-shaped items in prose to a list
• Bullets for unordered items; numbers for sequential steps or ranked items
• End prose that introduces a list with a colon
• Periods for complete sentences; no periods for fragments
• Labels must add information: avoid “Performance: Performance improved”. State the improvement directly
• For definitions, use - **Term**: description. Keep labels short; do not turn every bullet into a heading

Emphasis

• Bold for user interface elements or critical facts, not for tone. Rewrite a sentence that needs bold to sound convincing
• Do not bold every proper noun or acronym
• Inline code for paths, extensions, identifiers, and snippets: /api, .tsx, body, query
• No decorative emojis in headings or bullets

Punctuation & typography

• No em dashes or en dashes as punctuation. Split the sentence or use a comma; do not substitute a hyphen or parenthetical aside
• Prefer periods or commas over mid-sentence colons or semicolons. Reserve colons for lists or examples
• Curly quotes in prose: “text” and ‘text’. Keep straight quotes in code and literal syntax
• Ellipsis …, not three dots ...
• Use “and” in prose; reserve & for compact labels
• Non-breaking spaces between values and units, such as 10 MB

Data sizes & units

• Separate values from units: 64 KB, 5 KB, 200 ms, 30 s
• Preserve unit case: KB for kilobytes, ms for milliseconds. Do not uppercase every unit
• Keep units consistent; preserve exact syntax in code or quoted output

Source formatting & links

• One source line per paragraph; let the editor wrap the text
• One blank line before headings and around code blocks; no extra blank lines between list items
• No --- horizontal rules between sections
• Link text names the destination; never bare URLs or “here” and “link” as anchor text

Output format

For reviews without a requested format, group findings by file. Use file:line - issue; suggested fix for each finding. If the input has no file or line numbers, identify the section and quote the affected phrase.

Report each distinct issue once. Skip explanations unless the fix is non-obvious. If you find no issues, return “Pass”.

For rewrites, return only the rewritten text unless you were asked for an explanation. Do not append rationale, progress summaries, or plans.