Lexicon

A group spends disproportionate time arguing over a trivial, easy-to-grasp detail (the colour of the bike shed) while waving through the genuinely important, hard-to-grasp decision (the nuclear plant the shed sits next to). Everyone has an opinion on the trivial thing — so that’s where the discussion pools.

In the wild — tabs vs. spaces, naming conventions, and which shade of blue a button should be: the arguments everyone can join, so they crowd out the design nobody feels qualified to question.

From my own work — I automate every trivial standard instead of debating it. That is what Prettier, Biome, ESLint (JS/TS) and gofmt (Go) are for: pick one auto-formatter on day one and let it decide. Someone always dislikes a rule, but consistency beats personal taste.

Start from the parts and work up. You build the smallest, most concrete pieces first — get each one solid and tested — then compose them into larger structures until a whole system emerges. The foundation is real before the shape exists.

It shows up everywhere the same way: in software you write well-tested utilities and base components and assemble them into pages (the spirit of Atomic Design); in a team ideas and proposals bubble up from the people closest to the work; in learning you master the fundamentals first, then build something with them.

The strength is feasibility and quality — every brick is sound, and you see real results early; the risk is losing the overview, assembling well-made parts that don’t add up to the goal. Its mirror image is Top-down.

The number of people who would have to be “hit by a bus” before a project stalls because the knowledge to continue is gone. A bus factor of 1 — everything depends on one person’s head — is a flashing red light to write things down and share context.

In the wild — xkcd’s “Dependency”: all modern infrastructure resting on a project some person in Nebraska has thanklessly maintained since 2003. That is a bus factor of 1 holding up the world.

From my own work — this blog is a bus-factor-of-1 project — one person’s head — which is exactly why I over-invest in ADRs and docs. The write-up is the backup.

Copying code, structure, or rituals you don’t understand because they seem to be “how it’s done” — including incantations that serve no purpose in your context. The form is reproduced faithfully; the understanding that made the form work is missing.

In the wild — the origin image (from Feynman): after WWII, Pacific islanders built bamboo runways and headsets, faithfully mimicking the form of an airbase, expecting the cargo planes to return. In code: pasting a Dockerfile or CI config wholesale, keeping flags that do nothing here, because it worked somewhere.

A warning or condition attached to something that otherwise works: “this is fine, as long as X holds.” Unlike a Gotcha (a surprise nobody flagged) or a Pitfall (a trap you walk into), a caveat is a boundary the author draws on purpose.

In the wild — Redis is blazing fast, with the caveat that your dataset has to fit in RAM.

From my own work — I keep a Limitations section in every RFC: if a design scales horizontally but needs manual data-sharding to get there, I say so on day one — so nobody mistakes a temporary bridge for a permanent highway.

Don’t remove a fence until you understand why it was put there. The principle: before deleting code, a process, or a rule that looks pointless, first find out why it exists — the reason may be load-bearing in ways you can’t see.

In the wild — a weird-looking if guard or a retry with an oddly specific timeout. Delete it and a race condition or a rate limit you never knew about resurfaces in production.

From my own work — the line [run].bun = false in bunfig.toml looks pointless. It’s load-bearing: forcing Bun’s runtime on child scripts hangs astro dev (HMR stalls). The comment beside it is the fence’s sign — so I read the sign before reaching for the delete key.

Using your own product for real work before shipping it to others. The fastest way to feel the rough edges your users would — if a feature annoys you daily, it’ll annoy them too.

In the wild — Git and the Linux kernel, one of the purest examples there is. Linus Torvalds built Git to manage the Linux source, and the team develops both Git and Linux with Git itself.

From my own work — goshort, my own URL shortener. I run my daily links through it, so its rough edges surface on me before they reach anyone else.

A request to explain something in the simplest possible terms — no jargon, no assumed background — as if to a five-year-old. A good ELI5 is a strong test of whether you actually understand the thing.

A construct that compiles and runs fine but behaves in a surprising, counter-intuitive way. Unlike a Caveat (a limit the author documented) or a Pitfall (a trap you walk into), a gotcha is a hidden snag — the system’s design quietly disagrees with your intuition.

In the wild — JavaScript’s [1, 10, 2].sort() returns [1, 10, 2], because sort() compares numbers as strings by default. Or Go before 1.22: a loop variable captured by goroutines in a for loop yields only the last iteration’s value.

From my own work — React useEffect cleanups under Strict Mode. In dev, React mounts, unmounts, and remounts to surface leaks — so a listener or WebSocket without a proper cleanup gets duplicated, causing ghost state updates you can’t reproduce in production.

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviours of your system will be depended on by somebody. Coined by Hyrum Wright at Google — the reason “we never documented that” is no defence once people rely on it.

In the wild — a JSON API that happens to return keys in insertion order; clients start depending on that order, so “just sorting the keys” becomes a breaking change. Microsoft is famous for preserving bug-for-bug behaviour because shipped games relied on the bugs.

A minimum viable product is the smallest version you can put in front of real users that still delivers value, built to learn whether the thing is worth building at all. The point isn’t to be small for its own sake; it’s to test the riskiest market assumption with the least work, then iterate on what real usage teaches you.

Contrast a proof of concept, which proves something can be built (feasibility). An MVP proves people actually want it (desirability), while a prototype tests how it should look and feel. Popularised by Eric Ries in the Lean Startup movement, the term gets stretched a lot: reaching for “MVP” to describe what is really a PoC is a classic mix-up.

A common, foreseeable trap that’s easy to fall into — usually pulled by short-term convenience or over-engineering. Unlike a Gotcha (a surprising quirk of a tool) or a Caveat (a documented boundary), a pitfall is a strategic mistake: the system isn’t tricking you, you’re just walking a well-trodden path that predictably ends in tech debt.

In the wild — premature optimization: weeks spent on caching layers or microservices for an unreleased product, before there’s a single real bottleneck to measure — leaving a fragile system that’s hard to refactor.

From my own work — letting config files drift as copy-pasted text across repos. With no single source of truth, small differences between dev, staging, and production quietly cause deploy failures that are exhausting to debug.

A proof of concept is the smallest thing you can build to answer one question: will this actually work? You point it at the riskiest technical unknown (a tricky API, an algorithm, a third-party integration) and prove the approach is feasible before committing real effort. It is usually internal and often thrown away once the question is answered; the value is the answer, not the code.

Don’t confuse it with an MVP. A proof of concept validates feasibility (can we build it?); an MVP validates desirability (do users want it?). A prototype is the third sibling, testing how the thing should look and feel. Calling a feasibility spike an MVP is one of the most common mix-ups in product work.

A rough, practical guideline that’s good enough most of the time — not exact, not always right, but cheap to apply and usually close. You reach for it to make a fast call without running the full calculation.

A one- or two-line summary placed at the top (or bottom) of a long piece so a reader can grab the gist without reading the whole thing. Writing a good TL;DR forces you to find the single most important point.

Start from the whole and work down. You begin with the big picture — the goal, the overall system, the outline — and repeatedly break it into smaller parts until each part is small enough to tackle directly. The shape is set first; the details get filled in last.

It shows up everywhere the same way: in software you design the architecture and modules before writing any function; in a team a leader sets the goal and cascades it down into tasks; in learning you start from the thing you want to build and drill into the details only when you hit them.

The classic articulation is Niklaus Wirth’s stepwise refinement (1971) — refine a vague specification in small steps until it becomes a program. The strength is direction (you rarely lose sight of the goal); the risk is that the big picture can stay vague while the hard details hide at the bottom. Its mirror image is Bottom-up.

The internal mechanics beneath the clean interface you use every day. You reach for it when an abstraction leaks — fails or behaves oddly under load — and you need the real model, not the black box, to engineer around.

In the wild — React’s Virtual DOM diffs with an O(n) heuristic instead of a general O(n³) tree comparison. Or Git, which under the hood is a content-addressed key-value store of blobs and trees.

From my own work — learning how Node’s event loop and libuv thread pool actually work changed how I debug performance. When API latency spiked under heavy crypto load, knowing crypto.pbkdf2 blocks thread-pool workers let me raise UV_THREADPOOL_SIZE instead of blindly scaling out containers.

The chain of seemingly-unrelated sub-tasks you must do before you can do the thing you actually set out to do. You want to fix a bug → which needs a library update → which needs a newer runtime → which needs a config migration… and now you’re “shaving a yak” with no memory of why.

In the wild — the original, coined at the MIT AI Lab: someone trying to overnight a document, which needs a courier account, which needs a purchase order, which needs… a yak, somewhere, waiting to be shaved.

From my own work — to fix a term-dialog bug on my iPhone I had to reproduce it in WebKit, which meant running WebKit on Arch Linux, which meant hand-shimming icu74 and libflite into Playwright’s browser bundle. Two hours of yak-shaving for a one-line CSS fix.