Writing lean

The code and its specs are the first source of truth: a reader new to the project should learn it by reading them. Writing is lean when it carries only what they cannot say.

• Code first. Reach for a clearer name, a smaller function or a sharper spec before a longer explanation.
• One word per idea. Use the project's term for a concept, from GLOSSARY.md or the code, every time; a synonym reads as a second concept.
• Say what to do. State the target ("one-line comments"), not the ban; a prohibition earns its place only as a hard guardrail, paired with what to do instead.
• Once, where it bites. Each fact has a single source of truth, below; anywhere else, link to it.
• History goes to the story. What was weighed and what was rejected belong in the issue, pull request or commit, where the discussion and the diff sit beside them and git blame leads back.

The deletion test is the bar for every sentence you write or touch: delete it and ask what a competent reader loses. If nothing, the code already said it, and it stays deleted.