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.

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.

  • 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.

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.

  • 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.

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.

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 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. 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 a few kilobytes of JavaScript, and no build step. Most of what a first visit costs is the three fonts and the logo, and they are cached from then on. That is a small thing, but it is checkable, which is the point.