No More Free Rides

Amazon's retail site went down three times in a single week this spring. The worst of it was a six-hour blackout of checkout and account access. Many companies experienced similar issues. When you're Amazon, the news is everywhere.

The cause of the outages is where I want to focus. Amazon's own account pointed to an engineer who acted on bad guidance an AI agent had pulled from an internal wiki. The wiki, like almost every wiki anywhere, was months out of date. The agent didn't hallucinate anything. It faithfully reported exactly what the organization's own documentation told it, and the documentation was wrong, because keeping it right had never been anyone's actual job.

Amazon's fix, reportedly, was to add senior-engineer sign-off before AI-assisted changes ship. In other words, the company intentionally added human gates to slow down the delivery process. When I read the news my first thought was, "...but you're Amazon!" Surely Amazon must have a better way. Surely Github, just as much in the news for outages in 2026, must have a better way. These are not fly-by-night companies. They are mature engineering organizations with thousands of competent professionals and an unlimited budget to address AI-related software problems. Is this really the best they can come up with? And if so, what chance do the rest of us have in preventing the same kinds of problems?

Of course, I am overreacting. The sign-off fix is a reasonable stop-gap solution while more modern approaches are built. I wouldn't have put it in a press release, but at the same time I admire the honesty. And surely, better solutions are on the way. Aren't they?

The reason I like this example so much is because it's a perfect breakdown in Understanding, the second GUIDE principle for next-generation software engineering.

The Wiki Problem

Going back to Peter Naur's "Programming as Theory Building" once more, the product of a software team isn't just the software. It is the shared theory of how the system worked and how it failed. For as long as I've written software, wikis just like the one in the Amazon story were used to help maintain a knowingly imperfect story of a system. Someone would write it to help the next engineer, but by the time the next engineer read it, things had changed. This was part of the process. Humans know that they're not getting the whole story when they read a wiki about a system, and they know they need to augment their understanding with conversations, presentations, and real work in the system. They might even take the time to update the wiki when they're done, but the same problem persists.

AI changes things. The need for a shared theory of any software application is still necessary, but now that coding agents are doing the heavy lifting, that shared theory needs to be current at all times. And it doesn't stop at how the system works. It extends to include all the ways engineers work on the system: design patterns, coding preferences, fragile or untested parts of the system, known outages and incidents, failure rates, rates of change — the list can be extended ad infinitum.

There's an important subtlety to the way we're writing software today. When we use coding agents to write the code, we do not organically build a working theory of the software for ourselves. In other words, the engineering team doesn't understand the system simply by nature of building it. The theory must be built intentionally.

Understanding as Infrastructure

This is what the Understanding principle is naming: institutional knowledge stops being something engineers carry around and becomes something the organization has to deliberately build, maintain, and keep current the same way you'd treat a production database, not a wiki that nobody owns.

Vendors have started shipping products in this direction already: knowledge layers that compile organizational context into something an agent can query directly, instead of every agent reconstructing the picture from scratch. This is a good start, but it's not sufficient on its own, because a knowledge layer built on top of the same unmaintained wiki just serves stale answers faster and with more apparent authority.

Keeping documentation current needs to become a real, owned, resourced piece of engineering work, not a value everyone nods at in a retro. Amazon's sign-off gate might catch the next engineer about to act on bad advice. It does nothing about the advice still sitting there, waiting for the next one, human or agent, who doesn't get caught.

Naur was writing about human teams building a shared theory through the ordinary friction of doing the work together. Forty years later, we've lost the free ride. Somebody has to build the theory on purpose now. That's the whole premise behind GUIDE: implementation got cheap, understanding didn't, and the organizations that treat that gap as an actual design problem are the ones building a sustainable advantage in their engineering organizations.