The Verbal Architecture Decision Is the Most Expensive Kind

A Question That Costs Nothing - Until It Costs Everything

We were about 40 minutes into a product build call. Scraping was done. The chatbot flow was working. We were making real progress. Then one of my developers asked, almost in passing: "Which database should I use?"

I answered. He nodded. We moved on.

No ticket. No doc update. No comment in the repo. Just a verbal answer on a Zoom call that vanished into the ether the moment we hung up.

That question - and that answer - will cost us. Maybe not today. Maybe not next month. But the day we bring on a new developer, or the day something breaks in an unexpected way, or the day we want to refactor that section of the codebase, someone is going to look at that database choice and ask: why did we do it this way? And there will be no answer. No author. No reasoning. No context. Just a decision hanging in the air with no parent.

This is what I'm calling a verbal architecture decision. And I'm convinced it's the single most expensive category of decision a small technical startup makes - precisely because it feels free.

What Makes a Decision "Verbal"

A verbal architecture decision is any structural technical choice - which database, which table schema, which data flow, which API design - that gets made on a call, in a Slack thread, or in someone's head, and never gets written down in a place that future contributors can find.

The reason these are so dangerous is that they feel completely harmless in the moment. You answer the question. The developer goes off and builds. The sprint continues. What you don't see is the compounding interest that starts accumulating from that moment forward.

On that same call, we were deep in a real decision tree. My developer was asking about whether to create a new database, or add to an existing one. There were multiple databases already in play - each created for a different chatbot context, keyed to a chatbot ID. The question was legitimate and load-bearing: pick the wrong structure now and you're paying the refactor tax six months from now during a product sprint you can't afford to interrupt.

I gave him my answer. We figured out the right call together - use the existing database structure, create a new table keyed to the chatbot ID, make it retrievable with the same latency profile as everything else already in the system. It was actually a good decision, arrived at through real reasoning. The problem is that reasoning lives only in my memory and his memory. And one of us will forget it, or leave, or get busy.

That is the moment technical debt is born. Not when you write bad code. When you make a good decision and fail to record why you made it.

The Scale of What Gets Lost

Look at what we were actually building on that call. We were building an AI-powered chatbot system with URL scraping, labeled link extraction, dynamic Q&A generation, lead scoring via Zapier automation, LinkedIn profile inference, domain-based company enrichment, and a multi-step UI flow with parallel generation states. This is a genuinely complex product. And in a single session, we made decisions about:

• Which database and table to store scraped URL content in
• How to key that data (chatbot ID as the unique identifier)
• How to sequence the "save and generate chatbot" flow versus the "generate common questions" flow
• How to handle the timing gap between parallel async operations to prevent UI race conditions
• Whether to use a loading popup or a disable state to block premature user interaction
• How to format the prompt so Q&A takes priority over training data
• Where to inject URL references so the chatbot cites specific pages when answering

Every single one of those is an architecture decision. Every single one of those was made verbally. And as of the moment we hung up, none of them had a home.

Why Teams Don't Write This Stuff Down

I'm not pointing fingers here - I do this too. Everyone does. The reason is simple: writing things down in the middle of a fast-moving product session feels like friction. You're in flow. You're solving problems. Stopping to document feels like it slows you down.

But that intuition is wrong, and it's worth understanding exactly why.

The cost of writing down a decision is paid once, right now, when the context is completely fresh in your head. The cost of not writing it down is paid repeatedly, by multiple people, often under pressure, every single time someone needs to understand why the system looks the way it does. You're not avoiding the documentation cost. You're deferring it with interest.

And there's a second, uglier cost: when you don't have the "why," you're at real risk of making the same decision twice - burning hours debating something that was already settled - or worse, making the opposite decision and quietly breaking an assumption that half the system depended on.

On our call, we ran into exactly this kind of thing. The developer had built the scraping logic one way, and when we connected it to the frontend, we discovered the URL flow was broken because the original single-link use case had silently been replaced by a multi-link use case and nobody had updated the assumptions. The system was built on a decision that was no longer true, and there was no record of what the original decision had even been. Forty minutes of debugging a problem that a two-sentence doc would have prevented.

Architecture Decision Records: The Fix That Takes 10 Minutes

The software engineering community has had a working answer to this problem since 2011. It's called an Architecture Decision Record - or ADR. The concept was popularized by Michael Nygard, and it's since been endorsed by AWS, Google Cloud, and basically every serious engineering organization that has experienced the pain of undocumented decisions at scale.

The premise is simple: every significant architectural decision gets a short document - typically one page - that records the decision, the context that drove it, the alternatives that were considered, and the consequences. That document lives in the code repository, right next to the code it governs. It travels with the system.

The format that works for small teams is almost embarrassingly simple. Five fields in a Markdown file:

• Title - one line describing the decision (e.g., "Use chatbot_id as primary key for URL content table")
• Status - Proposed, Accepted, or Superseded
• Context - what problem forced this decision, what constraints existed
• Decision - what we decided and why
• Consequences - what gets easier, what new problems this creates, what the team now has to accept

That's it. You can write a complete ADR in ten minutes. For a decision like the database question we answered on that call, it would have looked something like this:

Title: Store scraped URL content in existing chatbot database, keyed by chatbot_id

Context: We need persistent storage for scraped link content (URLs + labels) associated with each chatbot. Multiple databases already exist in the system, each keyed to a chatbot_id. We considered creating a new standalone database for URL content.

Decision: Use the existing chatbot database. Add a new table with chatbot_id as the foreign key. This keeps all chatbot-related data co-located, reduces latency on retrieval, and avoids unnecessary database sprawl.

Consequences: Faster retrieval due to same database. New contributor must understand the existing schema before adding tables. If chatbot data ever needs to be sharded, URL content would need to move too.

That document takes ten minutes to write once. It answers the "why did we do it this way" question forever. And it does something else that's even more valuable: it forces you to think clearly about the decision before you commit to it.

The Verbal Decision Problem Is a Startup Problem Specifically

Large companies have architecture review boards. They have RFC processes. They have tech leads who sign off on design documents. It's bureaucratic and slow, but it does capture decisions.

Startups have Zoom calls.

The speed is the point - it's what gives small teams the competitive advantage. But the gap in the startup process is that the speed creates a documentation debt that almost nobody is tracking. Every verbal decision you make is a liability on a balance sheet that you're not looking at.

I've built and sold five SaaS companies. I've been in the chair on both sides of this - as the founder making verbal decisions on product calls, and as the person trying to understand a codebase that someone else built with no documentation. The second experience is genuinely painful. You're not just confused about the system. You lose confidence in the system, because you can't tell whether a given design choice was intentional and reasoned, or just an accident that happened to work.

When you have ADRs, you have something far more valuable than documentation. You have a record of intentionality. You can look at any decision in the codebase and see that a human thought about it, weighed alternatives, understood the tradeoffs, and made a call. That's what you want when you're inheriting a system, onboarding a new developer, or debugging something unexpected at 2am before a launch.

What a Verbal Architecture Decision Looks Like in Practice

Here's the thing about that call - and this is what makes it instructive rather than just cautionary. It was a genuinely productive call. We solved real problems together. The developer shared progress on scraping, on the URL labeling flow, on the chatbot generation sequence. We identified a real bug in the parallel generation timing. We designed a fix using loading popups to prevent users from triggering a second generation while the first one was still running. We talked through a Zapier-based lead scoring flow I'd built that could enrich incoming leads with website data and inferred LinkedIn profiles - and discussed how to integrate that enrichment into the product itself.

That's good, substantive product work. And all of it happened verbally.

The lead enrichment idea alone - where the system takes an email address, infers the domain, scrapes the website, pulls the LinkedIn profile, and then uses all that context to personalize how the product pitches itself to the user - that's an architectural pattern worth preserving in writing. Because when the next developer joins and sees a Zapier call firing on email input, they're going to wonder what the hell it's doing. And when I try to explain it from memory six months from now, I'm going to miss half the reasoning we worked through on that call.

The cost isn't in the decision itself. The cost is in all the invisible decisions baked into the implementation that never got named.

The One Habit That Changes Everything

I'm not asking you to write a design document for every feature. I'm not asking you to set up an architecture review board or an RFC process. Those are the right solutions at scale, but they're wrong for a team of two or three moving fast.

What I'm asking is this: at the end of every product call, before you close the laptop, spend ten minutes writing down the decisions that were made. Not the tasks - those go in your project management tool. The decisions. The choices that would be hard to reverse. The questions that got answered in a way that locked in a direction.

Drop them in a /decisions folder in the repo. Each one gets its own Markdown file. Title, context, decision, consequences. Done.

If you're not technical and your developer is building this for you, ask them to do it as part of closing out each call. Make it a five-minute end-of-session ritual, the same way you'd send a follow-up email after a sales call. (And if you want a framework for building those habits into your broader team process, the 7-Figure Agency Blueprint goes deep on operational discipline for growing teams.)

The teams that are best at this aren't the ones with the most sophisticated tooling. They're the ones that made it a habit before they needed it. Because by the time you need it - new developer, audit, acquisition, or a codebase that's grown past what any one person holds in their head - it's already too late to reconstruct the context that was obvious to you the day you made the choice.

The Real Cost Calculation

Let me give you the actual math on this.

Writing one ADR: 10 minutes.

Debugging a production issue caused by a decision nobody remembers making: 2-8 hours, minimum, for an experienced developer. Often more if the original decision-maker has left the team.

Onboarding a new developer without decision records: add 2-3 weeks to the time before they're genuinely productive, because they're spending that time reverse-engineering intent from code.

Rebuilding context for an acquisition due diligence: I've watched this process take months when documentation wasn't in place. Buyers want to understand the technical architecture and the reasoning behind it. "We made a lot of decisions verbally" is not a sentence that builds buyer confidence.

The ADR doesn't just save you time. In the right context, it saves the deal.

I built a lead scoring automation on that same call - a Zapier flow that takes an email, finds the domain, scrapes the website, identifies the LinkedIn profile from the name and company, and uses all of that to enrich the lead with location, industry, and company size before the sales flow even begins. I built it, explained it on the call, and described how it could be integrated into the product. That's real IP. That's a real competitive advantage baked into the architecture. And right now, the only place it fully lives is in a transcript and a Zapier account.

That's a verbal architecture decision. And it's going to cost me eventually.

Start Here

If you're building a SaaS, running an agency with a technical component, or managing any kind of development team - start this habit today. Not when you're bigger. Not when you have a CTO. Now, when the team is small enough that the habit is easy to install.

Create a /decisions folder in your repo. Write your first ADR about the last significant decision you made that isn't documented anywhere. Five fields, one Markdown file, ten minutes.

That's the entire ask.

The most expensive decisions you'll ever make are the ones that feel free in the moment. Verbal architecture decisions feel free because they cost zero time to make and zero effort to communicate. The bill comes later, in debugging sessions and onboarding friction and re-litigated debates and lost context and - in the worst cases - in deals that fall apart because the codebase looks like a mystery even to the people who built it.

Write it down.

If you want to go deeper on how to build operational habits that compound over time - whether in your sales process or in your product org - check out the free resources library. And if you're at the stage where you want live coaching on scaling the operational side of your business, that's what Galadon Gold is built for.