How I make a design decision, how I prove a change works, and how either one leaves my hands — written down as procedure. Both halves ask the same question: is this the simplest thing that works? One answers it by looking, the other by measuring.
Why it’s one method
I ask the same question on both sides of the work. On a design I answer it by rendering the options in the real system and looking at them. On code I answer it by measuring against a control. When the two disagree I go with the measurement, and I write down which one it was.
This is the part I bring to a team. I run these procedures at work, on a system where a wrong component ships to a lot of pages at once. They’re written as a spec an agent can execute, so a second person, or a machine, can run them without me in the room.
Two instruments
Design — the instrument is the eye
How a design decision gets made
- Render every option, in the real system — the actual typeface, tokens, grid, and breakpoints it ships in.
- Option 1 is always what’s live today. Without the baseline, “better” has no referent.
- A few distinct options beat a dozen near-duplicates. If two differ by 2px, they are one option.
- Pick by looking. The one-line reason comes after the choice: a reason written first is a prediction, and it will bend the pick to fit.
- Check both colourways and phone width before calling it done.
Build — the instrument is measurement
How a change gets proven
- Prove it on the real deployment. A unit test and a mockup are both hypotheses.
- Verify the change is in the live artifact before trusting a result. A failure against a stale bundle is a false negative.
- Pair every change with a control. A/B proves the change took; A/A proves nothing else moved.
- A visual signal when it renders, a trace when it doesn’t — the cheapest observation that can actually fail.
- Report the boundary of what was tested, and what wasn’t.
Both sides need a baselineIn design the baseline is what’s live today, rendered beside the alternatives. In engineering it’s the control arm of an A/B. Without one I can’t tell whether a candidate is better or just different.
Then the handoff
Messaging — the instrument is the sentence
How the work leaves my hands
- Answer first. A reader builds a hierarchy out of whatever order I hand them, so I hand them the true one. The order I found something in is almost never the order to explain it.
- If I can’t say it plainly, I haven’t finished thinking it. The write-up is the last place the work gets checked; it comes after the thinking and it is part of it.
- Say the strong thing, then say how sure I am. Confidence and accuracy are separate dials. Naming what I don’t know usually buys more trust than the finding it qualifies.
- The artifact carries the detail; the message carries the ask. If it’s linked, I don’t summarise it.
- Cut the part I’m proud of. The detail hardest to remove is the one that cost the most to find, and that cost isn’t the reader’s.
Rules for both
Rule 01Simplify by removalThe win is the thing that’s gone: a step, a file, a person in the loop. A thing tucked behind a disclosure triangle is still there.
Rule 02Decide by looking or by measuringNever by arguing. If a decision is being settled in prose, the wrong instrument is in use. Render it, or run it.
Rule 03Real conditions or it doesn’t countThe actual tokens and grid; the actual deployment. A mockup and a unit test are both hypotheses.
Rule 04Name the mechanism“Probably a race” is not a diagnosis. Either state the causal chain or say plainly that you don’t have it yet.
Rule 05State what was not testedPartial verification reported as complete is the failure mode that costs the most.
Form
Four markdown files in this site’s repo — method.md and one per side. A pointer file loads the root into every agent session I run; the side gets loaded when the task needs it.
What it isn’t
It encodes how to decide, so a fresh agent can run the procedures rather than recite the facts. It holds no biography, no dates and no decision log, and it is not a stand-in for a person.
Source
the four files on GitHub — the same text this page is checked against at build time.