Table of Contents
The hidden cost of AI adoption nobody talks about: your source of truth
I've seen teams burn sprint velocity not on bad code, but on disagreement about what the right code was supposed to do. That happened to us at Home Depot. Not because the code wasn't working, but because nobody could agree on where the ground truth lived.
That's the problem I want to talk about.
The setup
We're a small team – seven engineers, no PM. Building a library and an ML model from scratch. Not a massive platform, not a sprawling microservices architecture. A focused piece of software with a clear job.
And we still had a source of truth problem.
There's Spec Kit – GitHub's open-source framework for capturing product requirements in a structured, agent-readable format. The idea is sound: a consistent spec format that anyone (or any AI) can parse and act on.
And then there's JIRA – the execution layer, where engineers pull stories and leadership has eyes on velocity, burndown charts, and sprint reporting.
In theory, these two tell the same story. In practice, they diverge almost immediately.
Why they fight
Here's the tension: Spec Kit is designed to evolve. It's a living document – requirements get refined, details get iterated, and you're supposed to update it continuously. That's the point.
JIRA is designed to be stable. It's a commitment. When an engineer picks up a story, they're trusting that ticket to reflect what they're actually supposed to build.
Every time the spec changes, it creates a silent fork. The JIRA story that was written against the old version now describes a different thing than the spec does. Nobody flagged it. Nobody updated the ticket. The spec moved; JIRA didn't.
Now when an engineer picks up that story and hands it to the agent, the agent is working from the ticket. The ticket points at the spec. But which version of the spec – the one when the story was written, or the one that exists right now? Nobody knows. That's not a hypothetical. That's the default state if you don't build something to prevent it.
When both tools claim to be the source of truth, neither of them is.
How the cost actually lands
I saw this play out repeatedly. An engineer picks up a JIRA ticket that references the spec. The agent runs, the task is done in 10 minutes. Then it hits code review – and the reviewer is expecting something different. Not because anyone made a mistake, but because the spec had been updated mid-sprint and the ticket wasn't touched.
What should have been a quick merge turns into hours of back and forth: which version is right, what does the spec actually say now, what did the agent build against.
That's the real cost. Not the build time. The untangling time.
There's a compounding problem on top of this: specs get bloated. Ours would sometimes include exact file paths, directory structures, implementation details that don't need to be there. The engineer – or the model – can figure out the file path. What they need is the intent. When you over-specify, you create a document that's both fragile and high-maintenance. Every refactor, every rename becomes a spec update. Every missed spec update is another divergence point with JIRA.
And when the spec is thousands of lines long, nobody is reviewing every line. You skim the relevant section, trust the rest is still accurate, and move on. Most of the time that's fine. Until it isn't.
On a small team without a PM, nobody's job is to close that loop. We get pulled into code reviews, meetings, the next story. The cascade of JIRA updates just doesn't happen. Not because anyone is being careless. Because there's always something more urgent.
What about just fixing JIRA?
Every developer complains about JIRA. I get it. But it's not going anywhere.
Leadership uses it. The velocity metrics, the burndown charts, the sprint reporting – that data flows upward and runs decisions. You can hate the tool and still recognize that. The answer isn't to abandon JIRA or work around it. It's to stop expecting it to be something it's not.
JIRA is a tracking layer, not a requirements layer. The moment you treat it as both, you've created a conflict with no clean resolution.
What actually helps
A few things made a real difference for us.
Designate one tool as authoritative, explicitly. Pick a lane. When requirements change mid-sprint, updates go into both the spec and the JIRA ticket – and the engineer on that story gets notified immediately. Not later. Not at standup. The change and the notification happen together. Ambiguity usually wins because nobody closes the loop in the moment it opens.
Keep specs lean. Capture intent, not implementation. If a spec section describes what a function should do rather than where it should live, it stays accurate through refactors. The more implementation detail you encode, the faster it drifts.
Build update events into the workflow, not the culture. We use Codex to update the spec. Once that PR is reviewed and merged, the same agent pushes the relevant JIRA ticket updates via Atlassian MCP. The engineer on that story gets notified the moment it lands. Nobody has to remember to sync anything. The tooling closes the loop.
Normalize "which source?" as a default question. When someone shares a requirement in Slack, the first reply should be: "Is this in the spec, the story, or both?" The question itself becomes a lightweight forcing function.
The bigger point
The documentation problem is really a coordination problem. And the faster your team moves, the more every coordination failure amplifies.
Spec drift isn't a symptom of a careless team. It's a symptom of a workflow designed for a slower pace trying to keep up with a faster one.
The fix isn't a new tool or a new meeting. It's picking the one handoff in your workflow where confusion hurts the most and designing a specific rule for that exact moment. Not a process document. A rule. One sentence, one owner, one trigger.
Start there. The rest follows.
We're still figuring this out too. AI-assisted development is new enough that most teams are making up the process as they go – us included. We don't have a perfect system. We have a set of rules that worked better than what we had before, and we keep adjusting. The teams who are honest about that tend to move faster than the ones pretending they've already solved it.