Last week I audited this blog’s repository — the one that builds the site you’re reading right now — and I’m going to show you what I found, because you should never trust a hygiene sermon from someone who won’t show you their own kitchen.
The audit found 39 broken internal links across 15 posts — live, in production, for months. Every one was written as /posts/<slug> when the site routes posts at /posts/<category>/<slug>, and nothing — not the build, not a test, not a dashboard — ever said a word.
It found a frontmatter field the docs called required on every article. Twenty-eight of forty-five posts didn’t have it. The rule was real and sincerely believed; it was enforced by nothing, so it held only as long as whoever was writing happened to remember it.
It found three eras of dead documentation in the repo’s own instructions file — rewritten workflows, moved paths, a “known debt” note for a problem a later section claimed was solved. Whichever paragraph you trusted determined which wrong thing you did.
And it found a careful reviewer flagging the dev-branch preview for showing unpublished drafts — behavior that is intentional, so posts can be proofed before they go live. The decision lived in someone’s head instead of on the record, so the audit rediscovered it as a bug, and time got spent un-fixing something that was never broken.
None of this was carelessness. Every problem was created by a reasonable person doing reasonable work under normal deadlines. That’s the uncomfortable part, and it’s the reason this series exists.
What a Kitchen Knows That We Keep Forgetting
Mise en place — “everything in its place” — is the discipline professional kitchens run on. Before service, every station is set: onions diced, sauces portioned, knives where the hand expects them. During service: clean as you go.
What matters is that mise en place is not tidiness. A kitchen sets its stations because during the rush there is no time to look for anything. A kitchen that skips prep doesn’t fail at midnight when it’s quiet. It fails at the 6:30 dinner rush — the exact moment failure costs the most.
Hygiene Debt Compounds Invisibly
Code debt announces itself — updates and patches take longer, flaky tests get flakier, someone eventually suffers enough to fix it. Hygiene debt’s natural state is silence. Those 39 links produced no error, no log line, no failing check. The routing changed, nothing swept the old posts, and every article written afterward copied the pattern from the ones before it. Bad examples reproduce. Every existing file in your repo is a template for the next one, whether you meant it that way or not — the missing frontmatter field spread exactly the same way, until it wasn’t a rule anyone was breaking but a rule that had ceased to exist everywhere except the documentation.
The undocumented decision is the most expensive form of the debt, because it generates rework: an intentional choice with no written rationale is indistinguishable from an accident, so every fresh pair of eyes rediscovers it, flags it, and re-litigates it — or “fixes” it.
The interest rate is low enough to ignore on any given day. That’s the trap. Nobody ships a repo into disrepair in one commit; it happens one skipped field, one stale paragraph, one unrecorded decision at a time — and the bill arrives all at once, at 2 AM, denominated in incident minutes.
A Rule Is Not a Rule Until Something Enforces It
Here’s the before-and-after that turned this from an essay into a practice.
Before: the rule “every post must have proper frontmatter” lived in the documentation, enforced by human memory at 9 PM after the actual article was done. Measured result: 28 of 45 posts missing the field — a 62% violation rate for a rule that existed.
After: the same rule in two enforcing layers — the content schema declares the field required, and a lint script runs as the first step of the build, validating the whole corpus: the field, the tag taxonomy, category-matches-folder, link form, and a scrub for strings that must never publish. Miss the field now and the build fails, locally and in CI, naming the file and the rule.
The principle: documentation asks; CI insists. Not every preference deserves a pipeline gate — a kitchen laminates the health code, not the chef’s opinions about garnish. But any rule you’d call “required” has to answer one question: required by what? If the answer is “a sentence in a file,” you don’t have a rule. You have a hope with formatting.
One Practice, Several Stations
Repo hygiene is a practice, not a checklist — a set of stations, each prepped differently, serving one service. This series spends time at each:
Documentation that stays true. Docs the repo is periodically forced to agree with, where stale eras get deleted instead of accumulating. A doc that’s 70% right is more dangerous than no doc — no doc at least tells you to go look.
Decisions on the record. Lightweight ADRs, immutable once accepted, superseded rather than rewritten — so “why is it like this?” becomes a lookup instead of an archaeology dig.
Judgment encoded in runbooks. The difference between “restart the service” and “restart the service, unless the queue depth is climbing — check first.” The 2 AM instincts, written down at a calm 2 PM.
Rules enforced by machines. Anything you’d be embarrassed to explain in a postmortem (“the convention was documented, we just didn’t follow it”) belongs here.
Structural conventions. Where things live and what they’re named, decided once and made boring — so location carries information.
Changelogs that tell the truth. What changed and why, readable during an incident, when git log is a haystack and the needle is “what changed Thursday?”
Governed vocabularies. The small controlled languages every repo grows — tags, labels, severity levels. Ungoverned, they fork into synonyms (k8s, kubernetes, kube) until search quietly stops working.
Rules for AI teammates. The newest station, and the one that raises the stakes on the rest. Agents read your conventions, your examples, and your checks — and follow the actual state of the repo more literally than any human. A clean repo makes an agent dramatically more useful; a contradictory one makes it confidently wrong at machine speed.
Eight stations, one service. None of it is glamorous, all of it is prep — and the repo that has them set doesn’t need heroics during the rush. Heroics are what kitchens without mise en place call Tuesday.
Clean As You Go
The other half of the discipline keeps the first half from becoming an annual big-bang cleanup: wipe the board between tasks. Not at close. Not “when things calm down” — things do not calm down; that is the defining property of things.
In a repo, clean-as-you-go is small and specific. Stale paragraph in a doc you touched? Fix it in the same PR. Decision made in a review thread? Into the decision log before the thread scrolls away. Caught yourself violating a convention? Write the check that would have caught you. Each is a two-minute act.
I’d rather pay in two-minute installments. The repo whose hygiene is an operational practice is the one where the 2 AM runbook is true, the audit answer is a link, and the new hire’s first build passes — not because anyone was heroic, but because everything was in its place before the rush.
Happy automating!