deciding-what-matterslisted

# Deciding What Matters ## Overview Design is the act of deciding which information matters and making it prominent, while making everything that does not matter invisible. Those two halves are one job: every fact you leave visible competes for the reader's attention with the facts that actually govern behaviour. Code is obvious when a reader understands it quickly, correctly, and without conscious effort. Obviousness is a property of the reader, not the author, so it cannot be judged from the inside. ## When to use - Choosing what a module exports - A reviewer says "this is correct but I had to read it three times" - A function is short and still hard to follow - Deciding whether a detail belongs in a name, a type, or a comment - Naming and documenting a workflow's steps Not for: deciding module boundaries, which is [designing-deep-modules](../designing-deep-modules/SKILL.md). ## Core rules 1. **Decide what matters, explicitly.** For each module, list the facts a caller must know. That list is the interface. Everything else is implementation and must not be visible. 2. **Make what matters unmissable.** Put it in the type first, the name second, the doc comment third. Never only in prose far from use. 3. **Make what does not matter invisible.** Not merely unimportant- looking: absent. An exported helper nobody should call still costs attention every time someone reads the module's exports. 4. **Judge obviousness from outside.** You cannot assess your ow