Root-Cause Analysis for AI Builders: Don’t Stop at the Symptom
AI has made it possible for far more people to build and ship products without understanding every layer beneath them. That’s exciting — until something breaks. The hard part isn’t the building anymore; it’s the root-cause analysis that follows when your app slows down and you can’t tell why. This is the gap AI-assisted development has quietly widened, and closing it takes two skills most of us were never explicitly taught.
The Comprehension Gap AI Created
At last week’s Systems Distributed Conference, James Cowling, CTO of Convex, called this the Comprehension Gap: the distance between what you can build or operate and what you actually understand about the system underneath.
It shows up the moment something goes wrong. You understand your product at the level of the user experience. Then the app gets sluggish as customers pile in. You can see the symptom, but not whether the cause is the UI, the business logic, a slow query, or the way the database was designed.
That’s what makes the gap more dangerous than ordinary technical debt. With tech debt, you usually know where the problem is and what it’ll take to fix. With a comprehension gap, you may not even know which part of the system needs attention.
Here’s the thing, though. This isn’t new, and it isn’t really about AI. My tankless water heater taught me that years ago.
As AI makes it easier to build systems we don’t fully understand, technical leaders need two skills: tracing a problem to its real source, and explaining that source clearly enough for someone else to act. The rest of this post is about both.
With tech debt, you know where the problem is. With a comprehension gap, you may not even know which part of the system needs attention.
The $30K Comprehension Gap in My House
When we bought our home about ten years ago, we couldn’t find the water heater tank. The realtor said it was “tankless” — continuous hot water. It sounded great, so we didn’t ask many more questions.
For six years, it quietly worked. Then, three weeks before our third child was born, it stopped. The unit had never been set to recirculate hot water during peak hours. Worse, San Jose’s hard water had been building scale inside it the whole time, damaging several parts. Restoring reliable hot water meant replacing the unit, adding a water softener, and committing to regular maintenance — close to $30K all-in.
The failed heater was the symptom. The real problem was that we’d operated a system for six years without understanding how it worked or what it needed from us. Because my husband and I are both engineers, once we understood the system we could evaluate the fix, negotiate the warranties, and make sure we wouldn’t end up right back here. But first we had to trace the visible failure to its actual cause.
What Apple Taught Me About Root-Cause Analysis
For seven years at Apple, I worked across three product lines on the hardware side — about as “full-stack” as hardware gets. A problem that first appeared in the user interface could lead us all the way down to firmware, a component, silicon, or a step on the manufacturing line. You learn quickly not to stop at what the customer sees.
One of the disciplines for that is Early Field Failure Analysis (EFFA). When an early customer returns a failed unit, the work doesn’t end with repairing or replacing it. Even a single unit gets examined to understand what happened and whether others are at risk. Roughly:
- Triage the failure and reproduce the symptom.
- Narrow it to the responsible module or system.
- Assemble the right cross-functional team.
- Find the true root cause.
Start to finish, that can take a month to a quarter. Root-cause work rarely happens overnight.
The Same Discipline of Root-Cause Analysis Applies to SaaS
You don’t need a hardware line to use this. The same discipline applies even if you’re “just” building a SaaS app. When something breaks, you contain it with a hotfix, work out whether the visible UI issue is really business logic, the backend, or the database, decide on a longer-term fix, roll it out safely, and then measure whether it worked.
In other words: don’t stop at the symptom. Chase the system.
But finding the root cause is only half the job. You still have to explain it.
Finding the root cause is only half the job. You still have to explain it.
The Hard Part: Explaining What Really Broke
Technical leaders increasingly have to compress a lot of analysis into a short explanation for people with very different context. Engineers need enough detail to sanity-check the diagnosis. Senior leaders need the impact, the risk, and the tradeoffs. Customers mostly need to know what happened, what you’re doing about it, and when it’ll be resolved.
You can do excellent analysis and still lose the room if you bury the conclusion under the story of how you got there.
A framework that fixes this is BLUF — Bottom Line Up Front — which comes from the U.S. military. You lead with the conclusion or the decision you need, then give the context. It has two parts:
- The bottom line: one or two sentences with the conclusion, impact, and required action.
- The context: the supporting detail, rationale, and nuance that follow.
It helps people decide faster because they don’t have to hunt for the point. And it forces you to figure out what the point actually is.
Watch BLUF Work on My Water Heater as I Provide Root-Cause Analysis
Here’s the chronological version, the way I first told it: We bought a house. We learned it was tankless. Six years passed. It failed. A plumber came out. We learned about recirculation, hard water, scale, softeners, and maintenance. Eventually, we found out the fix would cost close to $30K.
Here’s the BLUF:
Bottom line: Our tankless water heater has failed and we’re out of hot water with a newborn due in three weeks. Restoring reliable hot water means replacing the unit, adding a water softener, and committing to regular maintenance — about $30K all-in. We need a go/no-go this week.
Context: The unit lasted six years but built up scale from San Jose’s hard water and too little maintenance, and the damage is too extensive to fix with spare parts. A softener plus scheduled servicing should keep it from happening again.
Same facts. But the BLUF hands you the problem, impact, solution, cost, and decision up front — then lets you opt into the details.
BLUF Isn’t Only for Providing Root-Cause Analysis on Incidents
That second skill pays off well beyond outages. The same move — lead with the point, then give the context — is how you make your own expertise legible, whether you’re writing a résumé bullet, walking an interviewer through a project, or making your case in a performance review. Most of us bury our best work under the chronology of how we did it. BLUF flips it: the impact and the decision first, the how second.
For more on the systems-thinking side of this, see my recap here of the Comprehension Gap talk from Systems Distributed.
Your Turn
Pick something you’re trying to get across right now — a technical problem you need a mixed audience to understand, or a piece of your own work you’re trying to convey in a job search, an interview, or an upcoming performance review. Can you state the bottom line — the outcome, the impact, and what you want the reader to do or take away — in two sentences, before any of the backstory?
That’s the whole game: chase the problem far enough to find the real cause, then communicate it clearly enough for someone else to act.
