writing-code-others-readlisted

# Writing code others read Apply `deciding-before-you-write` before changing code and `writing-for-the-reader` to names, comments, and docstrings. ## Contract - **Make the smallest complete change.** Follow existing architecture and style. Keep unrelated behavior stable. - **Put domain intent in names.** Choose names that expose the role, unit, state, or invariant a maintainer needs. - **Keep control flow visible.** Prefer direct data flow, short functions, and the language's ordinary constructs over speculative abstraction. - **Encode constraints mechanically first.** Use types, tests, validation, schemas, and tooling when they can state or enforce the rule. - **Use comments for residual knowledge.** A useful comment records a reason, warning, or contract that prose communicates most clearly. - **Keep provenance when it is evidence.** If a historical record is the only support for a constraint, name that source and its uncertainty. Write `Vendor rejects ≥1000 items (observed once: INC-482, unconfirmed contract)` while that incident remains the available evidence. After independent contract confirmation, write `Vendor rejects ≥1000 items`. - **Document public behavior.** A docstring describes the current contract, inputs, outputs, errors, and side effects that callers need. - **Verify the mechanism.** Run the narrowest check that proves the intended path changed, then the relevant regression checks. ## Process-leak check Code and comments describe t