Table of Contents
The hidden cost of AI adoption: source of truth
The PR looked right.
The agent had read the JIRA ticket, followed the linked Spec Kit file, written the code, and opened a PR in minutes. The problem was that the ticket and the spec no longer described the same requirement.
Review stopped being about code. It became an argument about which source of truth was real.
I watched this burn sprint velocity on our team. The loss came from disagreement about what the code was supposed to do. That happened to us at Home Depot. The code worked. The team could not agree on where the ground truth lived.
AI makes spec drift more expensive because it turns specs into execution inputs. When the spec is wrong, stale, or out of sync with JIRA, the agent doesn't hesitate. It builds the wrong thing faster.
The setup
We were a small team – seven engineers, no PM – building a library and an ML model from scratch. The project was not a massive platform or sprawling microservices architecture. It was a focused piece of software with a clear job.
It was also our first time implementing Spec Kit development. Spec Kit changed the handoff between planning and implementation: the spec became something an AI agent could read and build from directly.
There's Spec Kit – GitHub's open-source framework for capturing product requirements in a structured, agent-readable format. It gives the team a repo-friendly place to describe intent, constraints, edge cases, and decisions as they evolve.
JIRA is the execution layer, where engineers pull stories and leadership has eyes on velocity, burndown charts, and sprint reporting.
Spec Kit and JIRA should tell the same story. They diverge almost immediately unless you design the sync point on purpose.
Why they fight
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. In a Spec Kit workflow, that living document is not background reading. It becomes part of the implementation path.
JIRA is designed to be stable. A ticket is a commitment. When an engineer picks up a story, they're trusting that ticket to reflect what they're actually supposed to build.
When a spec change touches an active JIRA story, it creates a silent fork. The JIRA story written against the old version now describes a different requirement from the spec. Nobody flagged it. Nobody updated the ticket. The spec moved; JIRA didn't.
When an engineer picks up that story and hands it to the agent, the agent is working from the ticket and the spec together. But which version of the requirement is authoritative – the JIRA story as written, or the spec as it exists right now? Nobody knows. That's not a hypothetical. That's the default state if you adopt Spec Kit without also defining how JIRA stays aligned to it.
When both tools claim to be the source of truth, neither of them is.
How the cost actually lands
This failure mode repeated. An engineer picks up a JIRA ticket that references the spec. The ticket says the model should return { score, label } for each record. The spec has since been updated to require { prediction, confidence, rationale }, because reviewers need to see why the model made a call before they trust it. The agent runs, the task is done in 10 minutes, and the PR looks reasonable because it matches one of the inputs.
Then the PR hits code review, and the reviewer is expecting the newer behavior from the spec.
AI changes the timing. Before agents, a human engineer might notice the mismatch while reading through the ticket, the spec, and the code they are about to touch. Maybe they ask in Slack. Maybe they catch it during implementation. The friction gave humans time to notice.
The agent removes that friction. It can produce a coherent implementation from stale inputs before anyone realizes the inputs disagree.
Nobody was being sloppy. The agent built against the context it was given. The engineer reviewed the story they were assigned. The reviewer checked the latest spec. Each person had a defensible version of the truth, and that was the problem.
What should have been a quick merge turns into hours of back and forth: which version is right, what the spec says now, what the agent built against.
That's the real cost. Not the build time. The untangling time.
The bloat problem
Specs drift faster when they get bloated.
Ours sometimes included exact file paths, directory structures, and implementation details that didn't need to be there. The engineer – or the model – can figure out the file path. What they need is the intent.
When the spec becomes part of what the agent reads, bloat becomes more than maintenance pain. It increases the odds that the agent anchors on stale implementation detail instead of current product intent.
When the spec is thousands of lines long, nobody reviews every line. You skim the relevant section, trust the rest, 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. That made the failure mode easier to see, but I don't think the lesson is "just add a PM." The lesson is that Spec Kit development introduces a new lifecycle you have to own: spec changes, ticket changes, agent context, and reviewer expectations all have to move together.
Why JIRA cannot own requirements
Every developer complains about JIRA. I get it. But it's not going anywhere.
Leadership relies on it. Velocity metrics, burndown charts, sprint reporting – that data flows upward and runs decisions. The answer isn't to abandon JIRA. It's to stop expecting it to be something it's not.
JIRA is a tracking layer, not a requirements layer. It's optimized for assignment, status, sequencing, estimates, and reporting. Specs are optimized for intent, constraints, edge cases, and the context an engineer or agent needs to make the right tradeoff.
The moment you treat JIRA as both the execution tracker and the canonical requirements document, every spec change becomes a manual synchronization tax.
Agents make that tax more expensive because the work starts sooner. There is less natural time between "this requirement changed" and "a PR exists based on whatever context the agent was handed."
What actually helps
Make updates event-driven. We use Codex to update the spec. Each spec PR includes the linked JIRA ticket ID. Once that PR is reviewed and merged, the same agent pushes the relevant JIRA ticket updates via Atlassian MCP and notifies the engineer on that story. Nobody has to remember to sync anything. The tooling closes the loop.
That changed the shape of review. Before the sync rule, review threads started with "which version is right?" After it, they moved closer to "does this PR match the current spec?" That's a much better argument to have.
Pick one authoritative tool. For us, the spec owns requirements. JIRA mirrors the execution-relevant slice: story, status, owner, and changed acceptance criteria. When requirements change mid-sprint, updates go into the spec first, then the linked JIRA ticket – and the assigned engineer gets notified immediately. The change and the notification happen together, not at the next standup.
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.
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 becomes a lightweight forcing function.
Treat Spec Kit adoption like a workflow migration. The mistake is thinking you're just introducing a better spec format. You're also introducing a new artifact that agents may treat as implementation authority. That means you need rules for versioning, ticket sync, notification, and review before the team starts handing those specs to agents.
The bigger point
The documentation problem is a coordination problem. 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 human-paced handoffs trying to keep up with agent-paced implementation.
Fix the handoff where confusion hurts most. Give that moment a rule: one sentence, one owner, one trigger.
For us, the rule became: when a spec PR merges, the agent updates the linked JIRA ticket and pings the assigned engineer before implementation or review continues.
That one rule gave review a shared source of truth again.