How decisions are made

dqx has a plan document with numbered decisions — seventy-odd of them at the time of writing. Each records what was decided, when, and why, usually with a measurement.

That is not ceremony. It is what stops the same argument being had twice, and it is what makes it possible to change one's mind honestly: a decision that was right on the evidence available is not a mistake when better evidence arrives, and the record shows the difference.

Measure before deciding

The rule that produced the best decisions here: go and look.

• Which backend is fastest? Not "DDEV is known to be fast" — run all four on real projects and time them.
• Should the config keep a key? Not "it seems unused" — count how many projects set it.
• Can generated files replace committed ones? Not "probably" — diff the generated output against what every project actually has, and find out that none of them reproduce byte-for-byte and why.

Several decisions were reversed by their own measurement, which is the point of taking it.

Write the failure down

When something breaks in a way that was hard to see, the fix carries the story:

BusyBox's cp -an src/. . copies nothing and exits 0, so the whole scaffold vanished and the next step failed with Could not open input file: artisan.

Six months later that comment is the difference between a careful fix and a re-introduction.

Advice that cannot be followed is worse than none

A recurring lesson. A check that says "run this to fix it" and names a command that does not fix it costs more than silence, because the developer now believes the tool tried. Several remedies here were rewritten once somebody actually followed them.

Where the reasoning lives

The plan is a working document — open questions, half-decided items, things deliberately deferred — so it is not published as documentation. It sits in the repository, and so do the measurement-heavy documents behind the decisions: the backend comparison, the trials, the fleet inventory.

They name real projects, which is what makes them evidence rather than anecdote, and it is why this site carries the conclusions and the repository keeps the proof.