code-craft

Writing master-level code: the highest bar

This skill applies whenever code is written, modified, or reviewed, in any language, in any repo. It complements ../code-planning/SKILL.md (which covers the plan); this one covers the act of coding. The standard: the world's pickiest reviewer reads the diff and finds nothing unjustifiable. Not "nothing wrong", but nothing that cannot be explained in one sentence: why it is there, in that form, in that place.

The conviction beneath it all: code is read a hundred times more often than it is written, and debt always starts with a few lines nobody really looked at. Mastery is not using patterns; it is that everything present has earned its place, and everything else is gone.

---

1. Before writing: think, say, push back

• State your assumptions. If several interpretations exist, present them, never pick one silently. If something is unclear, stop, name the confusion, ask.
• Propose simpler when simpler exists. Challenging the request is part of the job: "a function is enough here, the event system you describe would cost more than it returns." Say it before, not after.
• Define "done" before starting: the test that will prove the behavior, the command that must go green. "Fix the bug" becomes "write the test that reproduces it, then make it pass." Without a verifiable criterion you are not coding, you are hoping.
• Work the smallest correct scope. Nothing beyond the request: no unrequested configurability, no error handling for impossible scenarios, no field "for later." If 200 lines could be 50, write the 50.

2. The law of abstractions: each one earns its place or does not exist

This is the heart of the highest bar. An abstraction (function, type, interface, layer, parameter, module) costs four times over: to understand, to name, to maintain, and to work around the day it turns out wrong. It exists only if it pays that back.

• An abstraction is justified by a real consumer, never by an imagined future. Rule of three: generalize at the third occurrence, not before. At the second, duplicate and note the seam where the generalization would go. Duplication is cheaper than the wrong abstraction.
• The four rules of simple design, in this order (Beck): passes the tests; reveals intention; no piece of knowledge lives in two places; fewest possible elements. The order is half the rule: never sacrifice readability to deduplicate a textual coincidence.
• Signs of a false abstraction, to delete without debate: an interface with a single implementation, no second one planned, no testing need; a layer that only forwards; a parameter nobody passes; a boolean that switches behavior (= two functions); a name with "And" (= two things); catch-all Manager, Helper, Utils, Service (= the domain was never named).
• The extension point is a new function, not one more parameter. When a need pushes a signature to grow, it is usually a second function asking to be born.
• "Make the change easy, then make the easy change" (Beck). If the code resists the modification, refactor first, in a separate commit, tests green before and after, then make the change that has become trivial. Never the two mixed together.