design-doclisted

# Design Doc Produce a structural design document that commits to the shape of a system before any code is written. The document is the seed artefact for everything downstream — contract derivation, leaf implementation, and composition all read from it. ## Why this skill exists When code generation begins without an explicit structural commitment, each step optimises locally. A class is added here, a wrapper there, a "just in case" abstraction somewhere else. There is no global view to push back against any individual decision, so the codebase accretes complexity that nobody asked for and nobody can later justify. A design document forces the global decisions to happen first, in one place, where they can be evaluated against each other. Once it exists, every subsequent generation step has a constraint to honour rather than a blank canvas to sprawl across. The discipline is the value; the document is the artefact that carries it. This is not a UML diagram and it is not a README. It is the smallest artefact that can fully answer: what modules exist, what is each one responsible for, what does each one expose, and how does data flow between them. ## When to produce a design doc Produce one whenever the work is larger than a single function or single file change. The cost of the document is small; the cost of an unconstrained generation that has to be unwound later is large. Skip it for: bug fixes scoped to one module, single-file scripts, experimental throwaway code the