Deep dives into software architecture, scalability strategies, developer experience (DevX), and system design for high-growth tech ventures.
Read the governance series in order
Most decision records keep the verdict and lose everything that would tell you, later, whether it is still right. Which fields earn their place, why the expected outcome and the assumption do different jobs, and how to make the record enforce itself in CI, with a template and the script to check it.
The contract your consumers depend on is not the one in your spec. It is everything they can observe: ordering, timing, a field that is always present, the wording of an error. Why versioning cannot protect that, why the producer never knows who depends on what, and what both sides can do before a perfectly compliant release breaks someone.
Environment isolation usually fails without an error: a credential drifts, a binding gets added in a hurry, and nothing complains until something writes to production. Four levels of making isolation provable, each with the code to do it, from refusing to boot with the wrong configuration to gating every promotion on a negative test.
Due diligence measures a supplier's posture on the day you sign. It says nothing about what it will cost you to leave, and that number does not stay still. Why the reversal cost of a bought dependency accretes after the signature, where it hides, and what to decide while designing the exit is still free.
Reversibility is not a virtue you buy for its own sake, it is insurance, and the premium is bounded by the damage it covers. Why paying uniformly is the real waste, why the cost of undoing a decision is created after the decision rather than at it, and what to record when you cannot price the bill in advance.
The series' last move: after writing decisions down, enforcing boundaries, isolating data, and encoding judgment, one guarantee is left that no technical control can reach — who has the authority to decide, and who owns the decision when it falls between owners. Why governance is ultimately an org-design problem, and what to do about it.
A scheduling shortcut for a mass-email system passed every environment and then melted down in production: thousands of emails never sent, thousands sent ten times over. It taught me that 'it passed review' was never the same as 'it's correct' — and why machine-speed code production makes leaning on human review indefensible.
For a legal-tech startup I had to guarantee that only authorized members of a tenant could ever touch its documents. RAG doesn't change that problem — it adds a retrieval layer that makes a soft boundary leak silently. Here is why tenant isolation has to be a hard pre-filter at the index, not a ranking signal, and why it must fail closed.
The pitch for multi-agent AI is that more agents mean a more powerful system. I paid that bill once — a nine-year experiment in splitting a platform across twelve separately-owned teams — and here is what it taught me about why the agent count is a cost you pay, not a capability you gain.
I opened my own repo and found that the rule meant to police my architecture enforced nothing. Here is how I turned it into a fitness function that fails the build when any code — human or AI — crosses a line it shouldn't.
In 2016, on my first architecture assignment, a mentor told me documentation was a deliverable as important as the code. Here is why the architectural decisions you don't write down always come back as debt.