The Specification Was Wrong Before the First Row Was Loaded
I spent the first ten years of my BI career receiving specifications I had no part in writing. They arrived as finished documents. My job was to build what they described. I did. And too often, what I built was wrong.
Not wrong because I misread the spec. Wrong because the spec itself was wrong.
If you are a BI developer, you know this moment. A specification lands on your desk. It comes from a Business Analyst or a department head. It describes what the report should contain. Your job is to make it real.
You read it. You have questions. Some of the KPIs are defined vaguely. Some of the data sources do not contain what the spec assumes they contain. The business logic in section three contradicts the business logic in section seven.
You raise these questions. Some get answered. Most get a version of: "Build what is in the spec. We can adjust later."
So you build. And you already know, from the first data model, that the report will not do what the requester imagines it will do. You know because you are the only person in the process who has looked at the actual data.
If you are a freelance BI consultant, you see this from the outside. A client hands you a specification written by someone who has never opened the data model. Your job is to make their vision work with their reality. The gap between the two is your unpaid overtime.
The common view is that the developer's job begins when the specification is complete. Requirements are gathered by analysts, approved by stakeholders, and handed to the build team. The developer builds.
This separation sounds logical. In practice, it guarantees the specification will contain assumptions nobody tested against reality.
The Business Analyst collects what stakeholders want. The developer knows what the data can deliver. These two perspectives meet for the first time at the build phase. By then, the specification is signed. The budget is committed. Changing the spec means a change request, a timeline impact, and a conversation nobody wants to have.
So the developer builds the spec as written. The report ships. And the first round of feedback reveals what everyone could have known in the first week: the specification described the requester's imagination, not the data's reality.
The developer sees the gaps first. They see that the fields the specification references do not exist in the source system. They see that the KPI definition in the spec produces a number that contradicts what finance reports quarterly. They see all of this before the first row is loaded.
In most organisations, that knowledge stays with the developer. It surfaces as a footnote in a status report. Or it surfaces after delivery as a change request the developer saw coming from day one.
This is not a developer complaint. It is a diagnostic. When the person who will build the report is excluded from defining what the report should contain, the specification is structurally incomplete. Every BI project that separates requirements from build creates this gap. The gap is not about competence on either side. It is about a process that keeps two essential perspectives apart until reconciling them is no longer inexpensive.
The freelancer who inherits a bad spec absorbs the rework in unpaid hours. The in-house developer absorbs it as frustration and overtime nobody tracks. Both carry the same structural failure. Both saw it coming.
If you commission BI reports, ask one question before the next build starts: did the developer review the specification before it was signed? Not after. Not during the build. Before.
If the developer's first encounter with the specification is the day they start building, the spec contains assumptions about the data that nobody has verified. Those assumptions become the change requests you will manage for the next three months.
If you are the developer receiving the spec, document what you see. The gaps you identify in the first week are the gaps the organisation will pay to discover after delivery. Making them visible early is the single highest-value action in the entire project.
A specification built from a brief handed down without the developer's input will be wrong before the first row loads. The rework compounds with every sprint built on those assumptions. Before the build phase starts, one structured session surfaces which assumptions in the spec will generate the most disruptive change requests.
Let the developer read the spec first.
One hour with the data model catches what three months of change requests will eventually reveal. We put the right people in the room before anything gets signed.
Talk to usFrequently asked questions
Why is the BI developer typically excluded from the requirements phase?
Organisational habit. Requirements gathering is categorised as a business activity. Building is categorised as a technical activity. The developer is assigned to the technical side, and nobody questions whether the boundary makes sense. It made sense when reports were simple extracts from a single source. It stopped making sense when BI reports became cross-system, multi-department analytical instruments with business logic embedded in every measure.
What should a developer do when they receive a specification they know contains wrong assumptions?
Document every gap before the first sprint. Write down what the data can and cannot support, which KPI definitions will produce contradictory numbers, and which data sources the spec assumes exist but do not. Send it to the project owner in writing, not verbally. That document is the evidence that the discovery gap existed before the build started. Without it, the change requests will be attributed to the build, not the spec.
Is it the Business Analyst's fault when the specification misses the data reality?
No. The BA's job is to capture stakeholder intent. The developer's job is to know the data landscape. Neither role is designed to do both. The process failure is structural: it assigns these roles to separate phases and never creates a moment where both perspectives meet before the spec is signed. The BA produced an accurate record of what stakeholders said. The developer knows what the data can deliver. The spec needs both, and most processes give it only one.
How does the specification gap affect long-term report adoption?
Reports built on a spec that missed the data reality get patched through change requests, but the patches address symptoms, not root cause. The report accumulates workarounds. Its logic becomes harder to maintain. Within a year, the developer who built it is the only person who understands why certain measures are calculated the way they are. When that developer leaves, the report degrades or gets replaced. The specification gap does not just produce rework. It shortens the report's useful life.