The spreadsheet is the spec

The spreadsheet is the real spec

Almost every internal-tooling or automation project we take on is replacing a spreadsheet, and the first thing we ask for is not a requirements document — it is the spreadsheet itself, with editing history intact if it is available. Clients are often mildly embarrassed to hand it over, apologizing for the color-coded cells and the tab called "copy of copy of March." They shouldn't be. That spreadsheet is the most accurate specification of the business logic we will ever get, and it is far more honest than any requirements document written to describe it after the fact.

A requirements document describes the process as the person writing it believes it works. A spreadsheet that has been used in production for two years describes the process as it actually works, including every exception someone patched in the moment it came up and never went back to formalize. Skip reading it and you will find out about that rule the hard way, from an angry email, three weeks after you replace the spreadsheet with a clean, well-architected system that quietly breaks for that one vendor.

Reverse-engineering before replacing

We treat the working spreadsheet as an artifact to be reverse-engineered before it is an artifact to be replaced. That means going through every formula, not just the ones that are obviously load-bearing, and asking the person who maintains it to walk through what each manual step is for, especially the ones they describe as "just something I do." The most valuable edge cases are almost always things nobody thought to mention in a kickoff meeting, because to the person running the process it is not an edge case — it is just Tuesday.

This matters more, not less, as the target system gets more sophisticated. When we are building an agentic AI system to automate a workflow that currently lives in a spreadsheet and someone's judgment, the spreadsheet's implicit rules are exactly what the agent needs to be evaluated against. An agent that handles the clean, common case well but misses the vendor-currency exception is not actually ready to take over the process — it is ready to handle 90% of it and quietly fail the 10% that the original spreadsheet, imperfectly, got right. Finding that gap during scoping is dramatically cheaper than finding it after the agent has been running unsupervised for a month.

What this means for the data model

There is an architectural lesson underneath this too: the data model of the replacement system should be able to represent every case the spreadsheet handles, even the rare ones, before you start optimizing for the common case. It is tempting to design a clean schema around the 80% of rows that look normal and treat the remaining 20% as something to handle later. In our experience that remaining 20% is where all of the real business value of the manual process was hiding, and "later" often means "during a stressful production incident."

None of this is an argument against replacing the spreadsheet — spreadsheets fail at scale, at concurrency, and at auditability in ways that matter a great deal once a process crosses from one person's desk into a team's daily workflow. It is an argument for treating the spreadsheet as the real spec, read carefully, before designing the system meant to replace it.

If your team has outgrown a spreadsheet that is quietly running a critical process, we would rather start by reading it with you than by whiteboarding an architecture from a description of it. Get in touch and let's look at what it is actually doing.