Put Decisions Where They'll Be Found


One of the easiest ways to create future confusion is to put a decision somewhere people are unlikely to look. Security rules hidden inside controllers. Rate limits embedded in random services. Business policies buried in emails. At the time it feels convenient. The context is fresh. Everyone involved remembers why the decision was made. A year later, the context is gone but the decision remains.

I saw this during a marketplace migration. One marketplace had very little traffic and the return on migrating it was not worth the effort. The team consciously decided not to migrate it. The decision was made. The problem was where the decision lived. It existed in an email thread. Later another announcement went out describing the migration as complete. Both statements were technically true, but the nuance lived only in people's memories. Months later an issue appeared. We searched documents, emails, and announcements trying to understand what was supposed to happen. The answer was not in any of them. The answer was in the code. The code still contained the exception and became the only reliable source of truth.

Tenet #4 — Make Assumptions Explicit. Every business rule, policy decision, exception, and constraint needs a home. A place where the next developer will naturally look. Before hardcoding a rule, ask: is there already a home for decisions like this? If yes, put it there. If no, create one. Decisions hidden in convenient places eventually become archaeology. Decisions placed where people expect to find them become documentation that stays alive.

Comments

Post a Comment

Popular posts from this blog

Breaking Systems, One Mistake at a Time

Image
I’ve broken more things than I’ve built — and that’s exactly why this blog exists. Over the years, I’ve learned that the most valuable lessons rarely come from perfectly executed plans. They come from the quiet moments after things break — when you realize what you missed, what you assumed, or what you could have communicated better. Most of those insights seem obvious in hindsight. This space, Obvious in Hindsight , is my running log of those realizations — from building reliable systems at scale to learning how people, teams, and code all fail (and recover) in similar ways. I’m writing to understand — out loud. Why I’m Doing This Every engineer I respect shares one thing in common: they remember what they got wrong. Not because they’re proud of the mistake, but because they learned something from it that documentation never could. This blog is where I collect my own version of those reminders — along with some movie quotes. Each post will tie back to one of my core tenets ...
Read more

Why Now Matters More Than the Idea

Image
Years ago, I proposed building a large data warehouse that captured how our creators structured their content. Everything. The semantics. The syntax. The patterns. Which HTML tags appeared together. Which musical octaves worked in combination. Which ad-tags influenced consumption. It was a massive idea. It was also far ahead of its time. The cost was high. The ROI was unclear. We didn’t know what we would do with the data. The idea made sense, but the timing didn’t. Five years later, things changed. GenAI arrived. Personalization matured. Analytics became deeper and cheaper. Suddenly, the same idea became useful. Now we had models that could learn from the patterns. Now we had creators who wanted insights. Now we had consumers who expected smarter experiences. The idea didn’t change. The world around it did. And with that, the timing flipped from “not now” to “why aren’t we doing this already?” It reminded me that ideas don’t win on its merit alone. They win when why , why now , and ...
Read more

Optimize for Being Less Wrong

Image
The brain learns in uncomfortable ways. When you repeat something you are already good at, very little changes inside. The wiring stays the same. But the moment you make a mistake, something shifts. The brain is agitated. You feel annoyed. Embarrassed. Restless. That discomfort is not failure. That is learning starting. No errors. No rewiring. The fastest learners are not the ones who avoid mistakes. They are the ones who make many small, high-quality mistakes and correct them quickly. LLM tools understand this instinctively. Tools like Claude, Cursor, or Cline don’t try to look good. They don’t protect their ego. They optimize for one thing only — being less wrong next time. They reduce their loss function again and again, billions of times. They don’t feel shame when they fail. They don’t slow down to preserve confidence. Humans do the opposite. We avoid mistakes. We repeat what feels safe. We do what makes us look competent. And that is how talented people plateau after yea...
Read more