Someone asked me last week to stop users typing backticks into a product-name field. Fine. Then someone asked for the same thing on a host-address field, then a description field. Three tickets, same shape, three weeks apart. That's the moment a form-validation ask stops being a bug fix and starts being a design question: do I bolt a fourth one-off regex onto a fourth page, or do I finally admit this is a pattern and give it a name?

We'd already answered that question once, for a different reason, and built a generic field-validation engine instead of scattering regex checks across pages. It lives in `fieldValidation.ts` as a rule registry, plus a `useFieldValidation` hook every form imports. Each field gets a small config object (`required`, `minLength`, `pattern`, `restrictedChars`, whatever it needs), and the hook hands back live sanitization, blur-time errors, and a submit-time gate. No new regex logic per page. That part isn't the interesting decision. The interesting decision is the rule we set for *adding to* the registry, and it's the same rule that governs a much bigger call: when do you carve a new bounded context out of an existing service, versus keep extending the one you have?

Here's the rule, stated plainly, because plain rules are falsifiable and vague ones aren't: **don't add a new named preset to the registry until the same logic is needed in two or more places.** Before that threshold, you route the requirement through `custom`, an escape hatch that takes a function and returns an error string or null. One-off logic goes through `custom`. Only once you've written functionally the same `custom` function twice do you graduate it into a first-class rule kind with its own key in the table.

This sounds obvious written down. It is not obvious in practice, because the pressure runs the other way. The moment you build one generic engine, every future request looks like it deserves to live inside it. That's the whole point of building the thing. Someone will ask for phone-number formatting and you'll be tempted to add a `phoneNumber` preset on request one, because you already have the registry open in your editor and adding a case feels cheap. It isn't cheap. Every named preset is a permanent addition to the table other developers now have to read, understand, and choose correctly between, forever. A registry with nine well-chosen rule kinds is a tool. A registry with thirty barely-distinguished rule kinds, half of them used exactly once, is a maze. The `custom` escape hatch exists specifically to absorb that pressure: it lets you say yes to the requirement today without saying yes to permanent API surface today.

Restricted characters were the exception that proves the rule, and it's worth being honest about why. `restrictedChars` shipped as a named preset from day one, before any second request existed, because we already knew, with high confidence, that every field touching a name or free-text description in this app was one incident away from someone pasting a backtick or a quote into it. That's not premature abstraction. That's abstraction based on a claim you can actually defend: "every text field in this category needs this," not "this one field might need this again someday." The distinction that matters isn't first-use-versus-second-use as a mechanical counter. It's whether you can name the population of future callers with a straight face. If you can, build the preset now. If you're guessing, wait for the second ticket.

That's the exact same test that decides whether a new feature deserves its own bounded context or belongs inside an existing one. Nobody splits out a reporting service the first time someone asks for a report. You extend the orders service, ship it, move on. The split becomes obviously correct the moment reporting's actual shape (its scaling profile, its data-access pattern, its release cadence) diverges from the service it's living inside, and that divergence is almost never visible from request one. It shows up on the second or third time you're fighting the host service's deploy schedule to ship a reporting-only change. Same test, wildly different stakes: a validation preset used wrong costs you a slightly messier table. A bounded context extracted wrong, or extracted too late, costs you months of migration and a service boundary drawn around the wrong seam.

The part people get backwards is thinking restraint is the safe default and formalizing is the risky move. It's the opposite, in both directions, depending which side you're guessing on. Refusing to name a pattern you can already see clearly (insisting on three more `custom` callbacks that are secretly the same function with different variable names) is its own tax, paid in duplicated logic and inconsistent error messages across pages. Naming a pattern before you can see it is a different tax, paid in an API surface nobody asked for and a table entry that quietly becomes dead weight. Both failure modes look identical from the outside: an engineer added complexity. Only the timing tells you which one happened.

One thing the `custom` hook made easier than I expected: cross-field validation. A `confirmPassword` check needs `ctx.allValues.password`, and because `custom` receives the whole values object, not just its own field's value, that fell out of the escape hatch for free — no separate cross-field validation path bolted on later. That's a small tell that the escape hatch was designed with enough headroom to actually defer decisions, rather than just deferring them until you're forced to special-case them anyway. An escape hatch that can't handle the requirements you're deferring isn't an escape hatch, it's a delay.

So the actual discipline isn't "prefer simplicity" or "prefer generality," which is the kind of answer that fits on a poster and helps nobody at 4pm on a Thursday. It's: know which side of the two-or-more-instances line you're standing on, for the thing in front of you, right now. If you're not sure, that uncertainty is itself the answer. Route it through the escape hatch and find out.

Someone asked me last week to stop users typing backticks into a product-name field. Fine. Then...

Don't add a new rule kind until you've written the same check twice

Tummala Krishna Kishore

I approved a pull request last month in about four minutes. Tests passed, the diff was clean, the checklist was all green. By every mechanical measure it was a fine review. 

It was also a rubber stamp, and I didn't notice until three weeks later, when someone tried to reuse the same "quick regex check" pattern for a fourth field and the file had turned into a pile of copy-pasted validation logic.

That's the gap I want to talk about.

## The Test for Real Design

A design review that only asks "does this work" isn't reviewing the design. It's reviewing the implementation. Those are different questions, and conflating them is how teams end up with codebases full of individually reasonable decisions that add up to a mess.

Here's the test I use now, and it comes straight from a validation engine I built recently for a set of React forms that kept accumulating one-off regex checks. 

The engine's rule registry currently has ten kinds:
* required
* minLength
* maxLength
* pattern
* forbiddenPattern
* restrictedChars
* numeric
* email
* custom
* sanitize

Every field a page needs validated gets one entry in a rules object, and a single hook wires up live sanitization, blur-time errors, and a submit-time gate off that same object. 

On paper, that's a nice piece of generalized infrastructure. The interesting part isn't the registry, though. It's the rule I attached to growing it: **a new named preset only gets added once the same logic is needed in at least two places.** Until then, you reach for the `custom` escape hatch and write it inline.

Nobody asked me to write that rule down. I added it after watching the opposite happen on a different project, where a "flexible" config object grew a new top-level key for every caller's pet requirement until it had thirty optional fields, and reading any one form's config meant mentally filtering out the twenty-six that didn't apply. 

Generality that isn't load-bearing yet is just clutter with extra steps.

## Catching Premature Generalization

This is exactly where most design reviews go quiet. Someone proposes a new rule kind — say, a `crossFieldMatch` preset because a signup form needs "confirm password." 

The review checks whether the regex works, whether it handles empty strings, whether there's a test. All reasonable. None of it asks the question that actually matters: 
> Is this the second caller, or the first? 

If it's the first, `custom` already does the job, and adding a named preset for one consumer is premature generalization dressed up as good architecture. It reads fine in the PR. Eighteen months later it reads as bloat, because nobody remembers why there are three ways to express the same rule.

A rubber-stamp review can't catch this. Catching it requires context the diff doesn't contain — how many other places in the codebase actually need this, and whether "two" is real or aspirational. That's not something a linter flags. It's judgment, and supplying it instead of a checklist is the entire point of having a design review at all.

I'll grant the obvious objection: *doesn't gatekeeping every new preset behind "prove you need it twice" slow teams down?* 

A little, sometimes. Someone writes the same three-line custom validator twice instead of importing a preset once. I think that cost is worth paying, because the alternative — a registry with fifteen presets, six of which exist for a single caller each — is worse and much harder to undo. 

You can always promote a duplicated `custom` block into a named preset once the duplication is real. You can't un-invent a preset that three other teams have already started depending on for reasons that have nothing to do with why you built it.

## Separating Logic from Framework Glue

There is a second question a real review should ask, and almost never does: **where does the pure logic live relative to the framework glue?**

In this engine, `fieldValidation.ts` holds nothing but rule definitions and pure validator functions — no React, no hooks, no component state. `useFieldValidation.ts` is the only file that touches React at all, and its entire job is wiring those pure functions into a component's lifecycle: `errors`, `sanitizeOnChange`, `validateField`, `validateAll`. 

That split wasn't originally deliberate. It happened because the pure functions were easier to unit test without a rendering harness. Only later did it become the reason the validation logic could survive a framework migration untouched. 

A rubber-stamp review doesn't ask "will this still work if the framework changes," because that question doesn't affect whether today's PR merges. A real design review asks it anyway. Today's PR is never just today's PR — it's a small vote on the shape of the next fifty PRs that get built on top of it.

None of this shows up in a green CI run.

That's the actual argument for keeping design review distinct from code review, rather than collapsing both into a single "LGTM" gate. Code review answers whether something is correct. Design review answers whether it's the right shape, and whether you're generalizing at the right moment — and that second question needs someone in the room asking it out loud, because the diff itself will never volunteer the answer.



I approved a pull request last month in about four minutes. Tests passed, the diff was clean, the...

The difference between a design review and a rubber stamp

Three boxes. That's what our C4 container diagram showed for the EPCIS batch upload flow in ALSC. Upload API. Processing Service. Notification Service. Clean. Presentable. Wrong in the way that actually costs you time during an incident.

Here's what one upload really does. A user drops an EPCIS batch file in the browser. That request lands on a Node.js Function. The Function writes the file to blob storage and drops a message on Service Bus. A .NET Function picks that up, does its work, and hands off to a Hangfire background job. The Hangfire job does more processing and puts more messages back on Service Bus for the next stage. Count them: browser request, Node Function, blob write, Service Bus message, .NET Function, Hangfire job, another Service Bus hop. Seven independent executions for one click. Three boxes on the diagram.

Nobody drew that. Nobody was going to, either. Not because the team was lazy. Because C4's container level was never built to answer "what actually runs, in what order, for this one business action." It answers a different question: what are the deployable units, and how do they relate to each other structurally. That's a fine question. It's just not the question you need answered at 2am when a batch upload fails somewhere in the middle of seven hops and nobody can say which one.

I want to be fair to C4 here, because the framework gets blamed for a gap it never claimed to fill. Dynamic diagrams exist precisely for this: sequence-style views of a specific runtime scenario, layered on top of the static container view. That's the textbook answer. In practice, on this project, we never drew one until an incident forced the question. I'd guess most teams doing async, queue-heavy work are in the same position. The container diagram gets maintained because it's the artifact everyone points to in design reviews. The dynamic view, the one that would have actually shown the seven hops, doesn't get the same attention because nothing forces it. Until something breaks.

And when something breaks, the cost of not having it is specific and boring: a support ticket references a failed batch, and resolving it means pulling in whichever four teams own a piece of that chain, each one grepping their own logs around a rough timestamp, hoping the clocks are close enough to correlate a batch ID by eye. That's not a hypothetical. That's what used to happen here before we fixed it.

The fix was distributed tracing with OpenTelemetry, and the part worth writing down isn't "we added tracing," it's the specific hop that made it necessary rather than nice-to-have. Hangfire's Redis-backed queue does not carry request context by default. A job dequeued by the Hangfire server has no idea which upload triggered it unless that link gets made explicit, in code, on purpose, by whoever wires the enqueue call. Every other hop in the chain (HTTP call, Service Bus message) has some natural place to smuggle a correlation ID through. Hangfire's queue doesn't hand you that for free. It's the kind of gap that only shows up once you actually try to trace something end to end, which is exactly why it never showed up on the container diagram either.

Once the trace ID actually propagates across all seven hops, the same incident resolves differently. Instead of four people grepping four log stores against a guessed time window, you pull one trace ID, open Application Map, and read the path the request actually took. What used to burn half a day now takes the time it takes to type an ID into a search box.

Worth saying plainly, though: turning on distributed tracing everywhere, always, is not free, and I'd push back on any advice that pretends otherwise. Trace volume maps directly to Application Insights ingestion cost. Blanket always-on tracing across every service, every environment, every request, is a line item, not a checkbox. We ended up building the ability to switch tracing on for a specific service only when investigating something, without a redeploy, rather than leaving it running everywhere by default. That's a governance decision as much as a technical one, and it belongs in the same conversation as the tracing rollout itself, not bolted on after finance asks about the Application Insights bill.

So here's the actual claim, not the softened version: a C4 container diagram that stops at "these are our services and how they call each other" is systematically going to undercount the real failure surface the moment you introduce a queue, and queues are exactly where async architectures live. Three boxes versus seven runtime hops isn't a rounding error — it's the difference between a diagram that looks complete and one that would have actually helped during the incident that eventually forced us to build tracing anyway.

If I were redoing the design review for this system today, I'd make one change to how we document it: no container diagram for an async pipeline gets signed off without a companion flow diagram showing at least one real end-to-end scenario, hop by hop, including the ones that don't carry context automatically. Not every scenario. One. The one that actually matters — usually the longest chain, or the one with the least obvious hop, like a Redis-backed queue that quietly drops your correlation ID on the floor unless you catch it.

The diagram wasn't wrong because it lied about anything on it. It was wrong because it stopped one layer too early, right where the actual failure surface starts. Draw the hops. The boxes were never the hard part.

Three boxes. That's what our C4 container diagram showed for the EPCIS batch upload flow in ALSC....

My container diagram had three boxes. The actual pipeline had seven hops.

Most architecture decision records fail for the opposite reason people think. The issue usually isn't that teams forget to write them. It's that the ones they write are filled with the wrong content. The key information a reader needs—why this option instead of the others—often gets buried on page three under a list of API changes.

An ADR has one job: capture a decision that is costly to reverse, along with the reasoning that led to it, while that reasoning is still fresh. That's all. It isn't a design document, a specification, or a collection of research. If you keep that focus, everything else about what to include or leave out will follow naturally.

**The format that still works**
Michael Nygard's original ADR template from 2011 (title, status, context, decision, consequences) has lasted for a reason. It directly addresses the key questions a future reader has: What was the situation? What did we decide? What did we give up? Teams that add ten extra sections, like owners, review dates, risk matrices, or approval lists, usually end up with a document no one finishes reading, which defeats the purpose. If your ADR template is longer than the time it takes to fill it out for a simple decision, cut sections until it’s more concise.

A useful rule of thumb is that an ADR longer than a page and a half is often a design document masquerading as an ADR. This isn’t a strict rule, but I haven’t seen a truly good ADR exceed 600 words. The decisions worth documenting this way can be stated, justified, and owned in about a page. If that's not possible, the record isn’t the issue. The decision is probably still tied up with other unresolved matters.

**What belongs**
The decision, stated clearly. "We will use event-driven integration between the order and inventory services instead of synchronous REST calls" is a decision. "The order service integrates with inventory" simply describes the current state and belongs in a wiki, not an ADR.

The challenges faced. Describe the two or three actual constraints that were in conflict, not a comprehensive literature review. For example, a latency budget versus consistency guarantees, team ownership boundaries versus a shared database that made those ownership lines unclear, or cost limits versus the vendor lock-in that comes with a cheaper option. If there was no real conflict, you probably didn't need an ADR.

The alternatives you seriously considered, along with why they weren’t chosen. Focus on the options a competent engineer would likely ask about six months later. For example, "We looked at a shared database with row-level locking; we rejected it because it recreated the coupling we wanted to eliminate between the two teams' deployment cycles." This simple statement saves the next person from rehashing a decision that's already been made.

The consequences, including the ones you’re not thrilled about. This is often the section teams skip, but it offers the highest value. Every genuine architectural decision comes with costs. If you adopt event-driven integration, you trade the simplicity of synchronous actions for eventual consistency and a tougher debugging process when a message is lost. Document that. An ADR that lists only the benefits isn't a valid record of a decision. It's a sales pitch to your future self, and future-you won’t be fooled more than once.

**What doesn’t belong**
Implementation details. Class names, endpoint paths, table schemas, retry counts—these change frequently and can quickly make the document outdated. If the ADR needs a code example to clarify its point, it likely indicates that the decision being documented is more about implementation than architecture, and it should belong in the code or design document instead.

Decisions that are not settled yet. If three options are still in play and no one has chosen one, that's a design document or a spike ticket. Writing an ADR for a decision still in progress creates a record that contradicts itself by the time it gets approved. Contradictory records are worse than having no records; they mislead the following reader.

A decision made after the fact to meet process requirements. This rubber-stamp scenario is more common than teams want to admit. Someone builds the solution and then creates the ADR retroactively because it's required by the checklist. The "alternatives considered" section becomes fictional, as nothing was actually considered. The option that got released is the only one that ever existed on paper. Readers can tell the difference. An ADR written after the code is merged feels different from one written beforehand. Once a team’s ADRs acquire a reputation for being just for show, people stop reading them, which is worse than never having them required.

Every decision, regardless of its importance. This is the trade-off people often avoid stating clearly: requiring an ADR for every non-trivial pull request leads to a pile of records. For example, both the choice to follow field-naming conventions and the decision to go fully async receive the same template and attention. The signal-to-noise ratio diminishes, and the truly important records—those concerning team boundaries, data ownership, or long-term platform choices—get lost among many similar entries about logging formats. Save ADRs for decisions that are genuinely challenging to reverse: those that affect team boundaries, data ownership, or a platform choice you'll live with for years. Smaller considerations can go in a pull request description or a design note.

**The crucial test**
Before you write the next one, ask yourself: if this decision turns out to be wrong in eighteen months, would the person troubleshooting it appreciate this document? If the answer is that they would skim through the generic content looking for the paragraph explaining why the obvious choice wasn’t made, write that paragraph first and build the rest of the record around it. Everything else, like the status field, review date, and approval chain, is optional. The reasoning is the key part; treat it that way, and the format will fall into place.

Most architecture decision records fail for the opposite reason people think. The issue usually isn't...