How we build

Engineering

The process work moves through, and what has to be true before it starts.

Process

How work moves

Every piece of work follows the same path. The order matters more than any single step: most engineering failures come from designing before the root cause is understood, or building before the design has been reviewed.

Each stage names the practice that governs it, and links to it. The practices are written as rules that can be applied or broken on a given day, not as values.

The engineering workflow Nine stages in sequence: problem, understand the system, find the root cause, design, review, build, validate, document, improve. Each stage names the practice that governs it. Problem A real constraint, not a feature request Understand the system Systems thinking Find the root cause First principles Design Long-term design, simplicity Review Three questions Build Reliability Validate Honest measurement Document Documentation Improve Carrying back what the last pass proved wrong The engineering workflow Nine stages in sequence: problem, understand the system, find the root cause, design, review, build, validate, document, improve. Each stage names the practice that governs it. Problem A real constraint, not a request Understand the system Systems thinking Find the root cause First principles Design Long-term design, simplicity Review Three questions Build Reliability Validate Honest measurement Document Documentation Improve Carrying back what was proved wrong
The loop is the point. Each pass starts from what the last one proved, not from where it stopped.

Review

What Review means

Review is not a sign-off meeting. Before anything gets built, three questions get asked, in order. Nothing more.

The three questions asked at review Three questions in sequence before building, each with what it means in practice. One: are we solving a real problem — a constraint someone actually hit, not a feature someone asked for. Two: do we understand it well enough to act — the cause, not the symptom it produced. Three: will this leave people more capable, without taking away their control or doing harm that cannot be undone — they can see what it does, they can change course, and they can undo what it breaks. Work that answers yes to all three is built. 1 Are we solving a real problem? A constraint someone actually hit, not a feature someone asked for 2 Do we understand it well enough to act? The cause, not the symptom it produced 3 Will this leave people more capable, without taking away their control or doing harm that cannot be undone? They can see what it does, change course, and undo what it breaks Build The three questions asked at review Three questions in sequence before building, each with what it means in practice. Work that answers yes to all three is built. 1 Are we solving a real problem? A constraint someone actually hit, not a feature someone asked for 2 Do we understand it well enough to act? The cause, not the symptom 3 Will this leave people more capable, without taking away their control or doing harm that cannot be undone? They can see what it does, change course, and undo what it breaks
A no to the first ends the work. A no to the second or third sends it back to design.

Practice

Seven practices, in five phases

Each practice governs a stage of the process above. Each is written as a test — something that can be checked against a specific decision, and that can be failed.

Understand

  • Systems thinkingGoverns: understand the system

    The unit of work is the system a change lands in, not the change itself. Before altering anything we establish what depends on it and what it depends on — a list that runs past the software to the people doing the work, and past them to the physical world underneath. The test: if a change requires a diagram to explain its consequences, the diagram gets drawn before the change gets made.

  • First principlesGoverns: find the root cause

    Before deciding whether to keep a system, establish why it exists and how it actually works — not how it is described. Inherited designs carry assumptions that were true once. The test: state the original constraint that produced the design, and check whether it still holds.

Design

  • Long-term designGoverns: design

    Some decisions are cheap to change later and some are not, and the two deserve different amounts of argument. A feature can be withdrawn next quarter. A data model, a public interface, anything holding a person’s records, or anything released into a living system will still be there in ten years, and every later decision gets built on top of it. The test: before committing, ask what it would take to undo this — and let the answer set how much evidence you need first.

  • SimplicityGoverns: design

    The smallest system that solves the problem is the one most likely to still be understood in five years, so complexity has to be argued for rather than assumed. The test: if a new component cannot be justified by a requirement that already exists, it does not get built yet.

Deliver

  • ReliabilityGoverns: build

    People use this software to earn a living, so a failure costs them more than it costs us. Correctness comes before new features when the two compete for the same week. The test: severity is ranked by what a failure costs the person using the system, not by how loudly it is reported or how awkward it is for us to reach.

Preserve

  • DocumentationGoverns: document

    Good engineering leaves a record. We write down what changed, why it changed, the alternatives considered, the evidence used, and what would make us reverse the decision. That last part is what makes a document useful two years later. The test: if we cannot explain our reasoning clearly, we probably have not understood it well enough ourselves. The notes are the public subset of this.

Evaluate

  • Honest measurementGoverns: validate

    What gets measured determines what gets built, so the choice of number is a design decision and gets argued like one. The number we optimise is whether the person finished what they came to do — not how long they stayed or how often they returned; time spent is a diagnostic here, never a target. The harder half is what no number will show. A cost that lands on something which cannot report it produces no complaint and no movement in any metric, so waiting for the data is the same as deciding it does not matter. The test: if a change improves our numbers by making someone need us more, say so out loud and justify it on its own merits — and if the honest answer to who would notice this going wrong is no one who can tell us, that case gets argued in words at review rather than waited for in the numbers.

Evidence

This website, as an example

A company that argues against surveillance should not surveil the people reading the argument. This site sets no cookies at all, carries no third-party trackers, no advertising pixels, and runs no analytics code. Fonts are self-hosted and subset rather than fetched from a third party, so no outside service is told who visited.

It is also plain HTML and CSS with no build step, and nine kilobytes of JavaScript on every page but /mark, which needs eighteen more to drive its camera. A text page costs about a hundred and forty kilobytes on a first visit — three quarters of that the three fonts and the logo — and two to six afterwards, once those are cached. Pages carrying pictures cost what the pictures cost; /mark, which is about a rendered object, is the heaviest at roughly seven hundred. That is a small thing, but it is checkable, which is the point.