Avoid generated prose tells

Generated prose often sounds polished while hiding that it did not learn the project voice. Phrases such as "seamless," "robust," repeated summary sentences, teaching-order narration, generic contrast language, and component-centered navigation copy make technical docs feel less trustworthy because they avoid naming the concrete behavior.

On documentation sites, generated tells often appear as "cards map," "pages carry," "domains expose," "the full map," or "how X should be reasoned about." These phrases narrate the catalog or the UI instead of naming the reader's destination, decision, artifact, or work area.

Use the detailed checklist below during prose review. A single occurrence may be fine; repeated patterns, clustered patterns, or patterns that replace evidence are the problem.

Familiar phrases can make readers suspect the writing is generated. Read the surrounding explanation before changing them: does the wording obscure the point, exaggerate it, or leave readers wondering what actually happens? Keep wording that explains the subject well.

Editing Without Losing Meaning

Read for meaning before cutting. Keep the reasons, conditions, qualifications, examples, and connections readers need to understand the subject. A shorter paragraph can make more work for readers if they have to reconstruct what the edit removed.

Try repairing a weak sentence first. Replace vague praise with the behavior that deserves it, or explain the consequence behind an importance claim. Delete a sentence if it adds nothing useful; do not delete it merely because its explanation also applies to other projects. Never invent a mechanism, number, or source to make a sentence sound more specific.

After editing, compare the explanations. Can readers still tell why the behavior exists, where it applies, what can go wrong, and what they should do? Restore any needed detail. Keep ordinary warmth and varied sentence lengths; splitting every relationship into short statements can make prose choppy and harder to follow.

Word Choice

• Magic adverbs. Cut adverbs that make ordinary facts sound secretly important, such as claims that something quietly, deeply, fundamentally, remarkably, or arguably matters.
• Stock AI verbs and adjectives. Replace "delve," "utilize," "leverage," "robust," "streamline," "harness," and similar defaults with the specific action.
• Ornate domain nouns. Avoid "tapestry," "landscape," "paradigm," "synergy," "ecosystem," or "framework" when a simpler domain word is accurate.
• Inflated copulas. Prefer "is" or "are" when grander substitutes like "represents," "marks," "stands as," or "serves as" do not add precision.
• Terminology churn. Keep the project's canonical term when it still names the same concept. Do not rotate through near-synonyms merely to avoid repetition; lexical variety can hide that several phrases refer to one type, command, state, or boundary.
• Abstract review language. Explain what readers notice, misunderstand, or need to decide. Phrases such as "a matched phrase prompts inspection" can sound procedural while hiding why anyone would care. Name the person and consequence if that makes the explanation easier to understand.

Sentence Structure

• Negative parallelism. Watch repeated not X, but Y reframes, causal reversals framed as "not for this reason, but for that one," X, not Y pivots, and "the question is not X; the question is Y" constructions.
• Countdown negation. Avoid stacking negated fragments before the point, such as "not this, not that, just the real thing."
• Self-answered questions. Cut rhetorical question fragments that ask and answer a question no reader needed answered.
• Repeated openings. Revise runs of sentences that start the same way to create artificial rhythm.
• Rule-of-three padding. Keep triples only when the three items are real and useful; avoid repeated three-part phrasing as decoration.
• Empty transitions. Remove "it is worth noting," "importantly," "interestingly," "notably," and similar transitions when they do not explain the relationship between ideas.
• Shallow participial analysis. Delete trailing -ing phrases that attach vague significance, legacy, importance, or broader meaning to a fact.
• False ranges. Avoid from X to Y constructions unless the endpoints sit on a real scale with a meaningful middle.
• Evidence-disclaimer cadence. Replace repeated phrases such as "supports," "does not independently establish," and "therefore" with the exact tested configuration, missing comparison, or remaining uncertainty. Repeating one caveat template makes distinct evidence look mechanically identical.

Paragraph Structure

• Punchy fragments. Do not split ordinary explanation into dramatic one-line fragments just to manufacture emphasis.
• Disguised listicles. If the paragraph sequence is really "first, second, third," either make it a list or rewrite the structure around the actual relationship.
• Blurred paragraph roles. Start a new paragraph when the subject, explanatory level, evidence type, or maintainer warning changes. A continuous block can hide that the prose moved from mechanism to history or from contract to speculation.

Tone

• False suspense. Cut "here is the thing," "here is where it gets interesting," "what people miss," and similar setup lines when the next point can stand directly.
• Forced analogy. Use analogies only when they clarify; avoid "think of it as" explanations that make an expert topic less precise.
• Speculative invitation. Avoid "imagine a world where" framing when the doc can state current behavior, planned behavior, or a concrete example.
• Performative candor. Remove faux vulnerability, fourth-wall asides, and "to be honest" framing that tries to sound authentic without adding a concrete constraint.
• Obviousness claims. Do not assert that the truth is simple, clear, obvious, or unambiguous in place of proving the point.
• Inflated stakes. Keep the consequence proportional; not every change reshapes an era, defines the future, or changes everything.
• Pedagogical filler. Cut "let's break this down," "let's unpack," "let's explore," and similar teacher voice unless the doc is intentionally a tutorial.
• Vague attribution. Name the person, document, report, project, or source; do not cite experts, observers, reports, or publications without saying which ones.
• Invented concept labels. Do not coin abstract labels such as a trap, paradox, divide, vacuum, or inversion unless the concept is defined and then used precisely.

Formatting

• Heading case. Use title-case headings in this repository. In other projects, preserve their established convention. Capitalization alone says nothing about the quality of the explanation.

• Dash pivots. Avoid repeated dash asides, dramatic pauses, and pivot clauses when commas, parentheses, semicolons, or shorter sentences would be clearer. Keep punctuation that helps readers follow a qualification or connection; do not apply a blanket ban on dashes, parentheses, colons, or semicolons.

• Bold-first bullets. Do not default every list item to a bold lead-in. Use bold labels only when the list is genuinely a field list or glossary-like structure.

• Decorative Unicode. Avoid arrows, smart quotes, and special symbols when project style expects plain typed characters or ASCII examples.

• Generation residue. Remove unintended chat framing, fill-in-the-blank prompts, source placeholders, internal citation tokens, and instructions addressed to the person who requested the draft. Preserve them only when the document intentionally demonstrates that syntax.

Composition

• Fractal summaries. Do not introduce, summarize, and re-summarize every section. Keep summaries for real orientation or handoff value.
• Exhausted metaphor. Use a metaphor once if it helps, then return to the system. Do not make the whole page carry the same metaphor.
• Historical analogy stacking. Avoid rapid lists of companies, eras, or technology waves as a substitute for direct evidence.
• One-point dilution. If a draft repeats one thesis through many phrasings, collapse it to the strongest claim and add evidence or examples.
• Content duplication. Check long AI-assisted drafts for repeated paragraphs, repeated sections, and near-duplicate sentences.
• Signposted endings. Avoid "in conclusion," "to sum up," and "in summary" unless the phrase is part of a real procedural or report structure.
• Formulaic concession. Watch for "despite these challenges" paragraphs that acknowledge problems only to dismiss them with an optimistic ending.

Additional Review Checks

• Hedged neutrality. Replace vague balance language with the actual uncertainty, tradeoff, or decision. Do not smooth a contested claim until it no longer says what the author thinks.
• Comprehensive padding. Cut checklist items, caveats, or "complete" coverage claims that add bulk without changing the reader's decision.
• Unsupported precision. Remove exact-looking numbers, rankings, timelines, or categories unless the doc shows where they came from.
• Apology and permission phrasing. Cut "sorry," "just," "hopefully," "feel free," and similar softeners unless the page is intentionally interpersonal.
• Vague action verbs. Replace "ensure," "handle," "support," "manage," and similar verbs with the concrete behavior, command, validation, or ownership boundary.
• Empty state scaffolding. Remove words such as "current," "complete," and "combined" when the named code, change, or test already supplies the subject and scope. Keep them when they distinguish a real version, completion state, or multi-part experiment.
• Local style discontinuity. Compare new prose with the surrounding project docs. Investigate abrupt changes in terminology, English variety, heading style, formality, or formatting, then restore consistency unless the document has a reason to differ.