The spreadsheet is the requirements document

A few weeks into a project last year, someone on the client side finally sent us the file. It was called something like Ops_tracker_FINAL_v7_use_this_one.xlsx. There were four tabs. One of them had a column with no header that turned out to hold the single most important piece of business logic in the whole company. The person who sent it apologized for how messy it was. We told her it was the best documentation we had seen from them.

That reaction surprises people, so we want to explain it.

What the meeting leaves out

When you ask a team to describe their process in a meeting, you get the version they wish were true. It is clean. It has a beginning and an end. Every case fits. Nobody mentions the customer who always pays late and gets handled differently, or the one region where the tax works backwards, or the step that only happens when a certain manager is on vacation.

The spreadsheet does not do that. The spreadsheet is where the team actually works, so it carries the record of every ugly thing they had to deal with. The conditional formatting that turns a cell red for reasons nobody can quite articulate. The tab named DO NOT DELETE. The formula with three nested IFs that encodes a policy decision from 2019 that was never written down anywhere else.

We read all of it. The half-finished columns tell us what someone tried and abandoned. The manual overrides tell us where the rules break. The comments left in cells are often a running commentary on the exact edge cases we are going to have to handle in code.

The columns nobody admits to

There is a specific pattern we look for now. Somewhere in most of these files is a column that people use constantly and describe to us never. A "notes" field that quietly drives decisions. A status that has six official values and, in practice, about eleven.

The gap between how a process is described and how a spreadsheet is actually filled in is where all the real requirements live.

When we find one of those columns, we do not treat it as a mess to clean up. We treat it as a question. Why does this exist? Who reads it? What happens if the value is wrong? The answers usually reveal a rule the team follows without thinking, which means it never came up in any conversation, which means we would have shipped software that got it wrong.

Turning the file into software without flattening it

The risk when you rebuild a spreadsheet as an application is that you smooth it out. The old file let a person type anything into a cell. Your new system wants a dropdown with five options. That feels like progress, and sometimes it is. Sometimes it quietly deletes the flexibility the team was relying on to do their jobs.

So we go slower on the parts that look messy. Before we replace a free-text field with a fixed set of choices, we pull the actual values people have typed and count them. Often the "chaos" is really twelve real categories and a long tail of typos. We can support the twelve and clean up the typos. What we try hard not to do is decide, on our own, that a case the team handles every week is not worth supporting.

Here is roughly how we work through a file:

• Read every tab, including the ones that look abandoned, and ask what each was for
• Trace the formulas back to the business rule they encode, then write that rule down in plain language
• Count the real distinct values in the "messy" columns before we constrain anything
• List every manual step and every override, because each one is either a feature or a bug and we need the team to tell us which

That last point matters most. A person doing something by hand is not always a failure of the system. Sometimes it is judgment that should stay human. We would rather leave a decision in a person's hands than automate it badly and have them stop trusting the tool.

Why we ask early

We ask for the spreadsheet in the first week, before we have written any code and often before we have agreed on scope. Partly because it saves everyone the trouble of describing in words what the file shows in five minutes. Mostly because the file changes what we build. We have walked into projects convinced we understood the work, opened the tracker, and realized the actual job was something adjacent to what the proposal described.

The spreadsheet has been the requirements document the whole time. The team just did not think of it that way, because to them it is only the thing they use to get through the day. That is exactly what makes it honest. Nobody writes a formula to impress an engineer. They write it because at some point the work demanded it, and the demand is still there, sitting in the cell, waiting for us to notice.