Design
The workspace for the thinking that happens before the first line of code, and the gate that stops the build starting until that thinking is done.
A design is a graph of typed nodes that grows from sparse to dense. When it is complete enough to defend itself, promoting it produces a plan whose steps are already in dependency order.
When it earns its place
Use a design when the work has unknowns — a schema nobody has designed, a contract between two pieces, an assumption about code nobody has read, an invariant that must survive the change.
The test is simple: if you can imagine discovering "oh, we also need X" halfway through the build, design it first.
Skip it for a one-line fix, an isolated bug, or a refactor with no shape change. Go straight to a plan.
What goes in the graph
Nodes are typed, which is what lets the gate reason about completeness.
- The spec chain — assumption, constraint, invariant, interface, test. This is the part that makes a design self-protecting.
- The implementation map — function, table, component, route, service, command, and the dependencies between them.
- The open work — question, decision, option, risk, security, reuse candidate.
Start from what already exists
On an existing codebase, inventory before you propose. For each major piece of the change, find whether the codebase already has an equivalent and name its fate: keep it, extend it, replace it, or delete it.
New nodes come after the existing ones are classified. Designing from memory rather than from the code is how a spec ends up describing the project as it was a year ago.
The completeness gate
Promotion is blocked while any of these is true:
- A question is still open.
- An assumption is low-confidence and untested, or has been invalidated.
- A hard constraint is contradicted by a decision.
- An invariant claims a test protects it, and no test points at it.
- An interface has an unresolved producer or consumer.
- A risk or security node is still open.
The gate exists to stop the "implement now, rationalise later" pattern. If it says the design is incomplete, the answer is to finish the design.
Note — a design is a self-protecting spec, not a document. The value is that the gate can tell you what you haven't thought about yet, which is exactly the thing you cannot notice by rereading your own notes.
Promotion is a boundary
Promotion happens in two steps: a draft you review, then materializing it into a plan. After that the design is frozen and the plan becomes the editable artifact.
The freeze is deliberate. A design that keeps changing after the build starts is a design that isn't governing anything.
Next: Plans.