clear-technical-writinglisted

# Clear Technical Writing Six weeks from now someone competent — often **you**, or an agent with no memory of this session — will open this PR or function because something broke. Every identifier will still be there. The *story* will not. Rebuilding that story from the diff is a tax on the *cold reader* — paid on every visit. Pay it once, at write time, while the context is still free. That is not niceness. A passage you cannot make clear is usually one you have not finished understanding. Explaining is how you finish. Write for a **teammate last here weeks ago**. Never talk down. There is no "internal, so cryptic" tier — a docstring is read while debugging, with less patience than a PR. **Concise ≠ cryptic:** cut filler, not the explanation the cold reader needs. Density is not professionalism. Optional second pass: `kookr-toolkit:clear-writing-reviewer`. ## Shape 1. **Intent first** — 2–4 plain sentences (1 for tiny fixes): problem, change, why. No function names, constants, or paths yet. 2. **Gloss jargon once** — project-specific compounds get a short definition on first use. 3. **Technical details next** — names, thresholds in words *and* constants, wiring, repo-relative paths. 4. **Verification last** — commands and outcomes (not a substitute for intent). ### Code documentation - **Docstrings lead with what and why, not the signature.** Types already state the shape; say what it is *for*. - **Comments explain intent, not mechanics.** The code already says *what