explain-in-simple-language

# Explain in simple language Comprehension is the only goal: the reader understands on the first read. Defines only the wording of what you say to the user; what to say (evidence, scope, structure) stays with whatever asked for the text. Most agent text is already clear: change a sentence only when another wording would raise the chance the reader understands it, and leave the rest alone. ## The reader A competent developer, fluent in English but often not native, who did not see what you just saw: the files, the tool output, your own reasoning. Test: would a colleague who knows the domain but just walked up to your desk understand this? ## Rules - **Name things concretely.** Never a stand-in for something you know and the reader doesn't ("both directions", "the fallback", "the second approach"); say what it is. Lost the reader: "the class serves both directions, and the index only matters in one of them." Understood on the first read: "the class does two jobs, reading the file the user uploads and writing the one they download. The index only matters for the reading job." Longer, and better. - **Words.** Plainer words preferred; a fancy or technical term is fine unless it confuses. Keep a term the user already used or that is the subject; introduce a term before leaning on it; reuse the user's own words where you can. - **Structure.** One idea per sentence, one point per paragraph. Concrete case before general mechanism. - **Depth.** Answer what was asked,...