The Guardrails File That Grew Itself

Covers July 2–30, 2026 · published August 2026

Last time I covered designing the vault itself. This time I’m going back to something from the very first installment: the guardrails file — the plain text document that tells the AI maintaining my notes what it may and may not do on its own. Part 1 summarised the core rules I started with as five plain guidelines. What I didn’t say then: those five were a plain-English summary of seven numbered rules, and the file didn’t stop at seven.

It’s at twenty-eight now. Not one of them was planned. Nearly every addition came from something specific that actually happened — a mistake, a near-miss, or a piece of work that quietly went missing — and none of them from imagining what might go wrong someday.

That’s the whole point of this piece. A rulebook you write on day one encodes what you can imagine going wrong. A rulebook that grows from real incidents encodes what actually goes wrong, and those two lists barely overlap.

Complacency caught by its own rule

One rule says: check ground truth, don’t trust a stale assumption. It exists because I almost broke it myself — a session nearly proceeded on a status summary that turned out to be several days out of date, caught only because a habit of checking the real log first was already in place. The rule that would have prevented the mistake is the same rule the near-miss produced. That’s not circular, it’s the loop working: notice a close call, write down what would have prevented it, so the next session doesn’t get the same close call.

A recommendation that hid inside a conditional

Another rule: any weighed pros-and-cons answer has to end with an actual recommendation, not an “if X then Y” left for me to resolve myself. It exists because that exact failure happened once — a carefully weighed answer that never actually said what to do. The fix isn’t “try harder next time.” It’s a standing rule that makes the omission structurally awkward to repeat.

The step that gets skipped under pressure

A four-part discipline — find the real root cause, fix it, then check the rest of the system for the same class of problem, then see if the mistake can be made structurally hard to repeat — sounds obvious written out. In practice, the third step is the one that gets skipped when you’re moving fast. It happened here: fixing one permission-matching gap didn’t trigger a check for the same brittleness elsewhere, and the same bug reappeared a few messages later in a different command. The rule now names that specific failure mode, so it’s harder to quietly skip again.

The check that could never have succeeded

This is my favorite one, because it’s the rule I’d never have thought to write.

A background loop was set up to watch for a job finishing. It watched for a log line containing the cycle’s start timestamp — a value that would never appear in the finish line. The condition could not occur. The loop would have waited forever and reported nothing wrong, because nothing ever looked wrong.

It was caught by checking the underlying log by hand instead of trusting the watcher. The rule that came out of it: before trusting any check, monitor, or alert as a safety net, confirm the thing it’s watching for can actually happen and would actually be detected. A verification mechanism that silently can’t succeed is worse than none at all, because it manufactures confidence instead of an honest gap.

I have now tripped over that same class of bug three more times while writing this series — each time a text search that structurally could not match what it was looking for. The rule doesn’t make you immune. It just means you recognize it faster.

Work that was finished and invisible

Two rules came from the same root cause, eight days apart, and the second was far worse than the first.

The first: a cleanup pass found an idle workspace that had been dead for two days, quietly holding seven real commits and a full written business plan. Nothing was broken. Nothing alerted. The work simply existed nowhere anyone was looking.

The second, worse: a cleanup pass — following the rule written after the first incident — correctly identified a workspace as dead and removed it. That workspace was dedicated infrastructure for a scheduled job. The job then died silently on startup, before its own first log line, on every one of its three-daily runs, for a full week. Nobody noticed, because a job that dies before it logs anything looks exactly like a job that had nothing to do.

The rule got rewritten. Running the rewritten version for real the same evening, it turned out the fix was itself wrong — it would have made it impossible to ever clean up anything, because it keyed off a marker that every workspace carries by default. Rewritten again. And in that same pass, a claim the new rule leaned on as precedent turned out to have been asserted rather than checked, which was wrong too. Three corrections to one rule in one evening, each caught only by running the fixed process rather than trusting the previous fix.

Watching never actually stops

One principle is the exception to everything above. It didn’t come from a specific incident at all — it’s a rule about attention itself: treat maintaining anything, a note or a server or a routine, as a loop that keeps running even when everything currently checks out, not a checklist you finish once. The instinct to stop watching once things look fine is exactly the instinct this one is built to interrupt.

Why this matters more than the specific rules

The actual lesson isn’t any one of these — it’s the shape they share. Look back at the list: a stale assumption, a missing recommendation, a skipped look-across, a check that couldn’t succeed, work that was finished and invisible. I would not have predicted a single one of them on day one. I’d have written rules about deleting files and leaking passwords, which are the things that sound dangerous.

The things that actually cost me time were quieter than that. Most of them shared a shape: something that looked fine and wasn’t, with nothing in place to tell the difference.

Don’t try to write the perfect guardrails file before you start. Write a conservative starting set, then treat every real mistake — yours or the AI’s — as information about a missing rule, not just something to quietly patch and move past.

With one limit I should state rather than let you find out the hard way. Learning from incidents only teaches you the failures you survived. Every rule in this piece came from something that went wrong and left enough behind to reason about — work sitting in the wrong place, a check that couldn’t fire, a claim that didn’t hold up. None of them came from something irreversible, because nothing irreversible has happened yet. That isn’t a method working; that’s a sample I got lucky with.

So the starting set isn’t a placeholder to be replaced by experience. It’s the part experience can’t teach you, and it’s worth noticing that my own day-one rules — never delete, never move, never restructure without asking — were written exactly the way I’ve spent this whole piece saying rules don’t get written: by imagining what might go wrong. They’re still there, unchanged, twenty-one rules later. Guess ahead of time about the things you can’t undo. Let incidents teach you the rest.

Try this right now

Think of the last thing that broke in a system you maintain, and ask one question: was there a check that should have caught it, and did that check actually run? If there wasn’t one, that’s your next rule. If there was one, and it didn’t fire, that’s a more interesting problem, and it’s the one worth writing down.

What comes next

Part 6 covers backup — specifically the real drill that found a backup already dangerously stale, and the fix that made sure it couldn’t happen quietly again.

If this helps you, check out my adblob to support the work.