AI Insights

Written by Lead Java Software Engineer Siarhei Dvaradkin

Wrong docs, wrong code

SDD frameworks follow a clear logic: describe what you want to build, let the AI agent plan and implement it, verify the result, and move on. The documentation serves as the instruction set: architecture, requirements, and design decisions. The agent reads it and builds exactly what it says.

This works well when the documentation is right. The problem is what happens when it isn’t.

A human developer can read stale docs, notice they don’t match the codebase, and adapt. An AI agent just follows the spec. If the architecture document describes a pattern the team dropped two tasks ago, the agent builds the dropped pattern. If the requirements include a constraint that was revised but never updated in the spec, the agent enforces the old constraint. Wrong docs produce wrong code. Not approximately. Literally.

And docs do go stale. That’s just part of building software. Waterfall had the same problem: documentation flowed between phases as the primary input, and it kept going stale. The industry moved to Agile, which treated docs as a helper, not the source of truth. When docs were outdated, developers used their judgment instead.

SDD can’t do that. AI agents need clear instructions. They don’t remember what changed in the last sprint. They don’t sense that the spec feels off. The documentation is everything they know. When it drifts, there’s nothing to fall back on.

When a decision changes, that change needs to be reflected in every document that references it. A requirement drops. A design improves. An approach shifts. This is change propagation. I believe it is the central unsolved challenge of SDD, and it is the framework’s job to solve it, not the user’s. The first step is acknowledging that the gap exists.

Why documentation drifts

So why can’t we just keep the specs up to date? It feels like a maintenance problem: stay on top of your docs, and the system works. But it’s harder than it sounds, because building software keeps working against you.

Think about what happens when a requirement changes mid-project. A stakeholder sees an early result and wants something different. This is normal. But in SDD, a changed requirement doesn’t just mean changing the code. Architecture, requirements, phase plans, and story files all reference the old decision. Miss one, and the old constraint lives on. The next task reads it, builds against it, and the drift adds up.

Requirements aren’t the only thing that changes. Sometimes what you specified upfront just turns out to be unnecessary once you start building. I ran into this with BMAD. The framework asks you to specify NFRs (non-functional requirements) up front, such as how many milliseconds a request should take. During implementation, I realised one of those response-time constraints wasn’t worth it: the request wasn’t performance-critical. I told the agent to drop the NFR. It removed the requirement and the test. But at verification, the same NFR came back as a missed requirement. The agent had removed it from one document but not another. I removed it again. Phases later, it came back again. The same dropped constraint kept surfacing because the change never reached all the places it was referenced.

The spec had already committed to that NFR, and implementation showed it didn’t matter. This happens a lot: SDD asks you to make design decisions up front, but some of those decisions can only be verified by actually building the thing. Edge cases, integration issues, and real performance numbers don’t exist when you’re writing the spec. When you find a better approach during implementation, that discovery stays in the conversation or the task summary. The long-lived docs that feed future tasks don’t get updated. Nobody has built the tooling that would do this automatically. Not because it can’t be done, but because the ecosystem hasn’t focused on it.

And drift doesn’t just come from decisions people make. It builds up quietly every time the agent makes a reasonable choice that the spec didn’t cover. Each phase adds small differences. The spec slowly stops matching what was actually built. Later tasks read the stale spec and either undo good changes or pile new contradictions on top. Information flows one way, from spec to code, and never back.

The propagation gap

SDD frameworks know that specs go stale. They offer ways to deal with it. BMAD has a course-correction workflow. GSD lets you insert or remove phases mid-milestone. Spec Kit says update the spec and regenerate. Superpowers have human checkpoints at phase transitions. Kiro offers Refine and Update Tasks flows to cascade spec changes downstream.

In practice, these don’t work as advertised. BMAD’s correction workflow asks the right questions, but it mixes real issues with stale ones, and you have to go through each one to tell them apart. Dabene describes the experience: “The system proves fragile if a constraint is forgotten at the start, making any backtracking laborious.” Spec Kit offers no way to update a spec piece by piece. Changing one requirement means regenerating everything. Superpowers, to its credit, doesn’t claim to have propagation tooling it doesn’t have.

The bigger problem isn’t that the tools are rough. They’re early, and early tools get better. The problem is that propagation is sold as solved when it clearly isn’t. Kiro’s Refine and Update Tasks flows are meant to cascade spec changes downstream, but in practice, the cascade is unreliable. A community member built spec-kit-sync to detect drift between specs and code, because the framework itself doesn’t. When the community builds workarounds, the problem is real.

Where the tooling stops, the work falls to the user: manually tracking which documents need updating after every change, doing it consistently across every phase, under deadline pressure.

That doesn’t scale. Keeping docs up to date is work that competes with building features. It has no immediate payoff because the feature already works, while the cost is real: time, tokens, and mental effort. Scott Logic tested Spec Kit and found that specifying and reviewing consistently took hours while code generation took minutes. When the overhead is that high, doc maintenance loses every time.

And here’s the kicker. BMAD’s own repository had stale references to deprecated workflows across 23 files  (PR #992). If the people who built the framework can’t keep their own docs in sync, the system is asking too much of its users.

Change propagation is not a discipline problem. It is an engineering problem. And it belongs to the framework.

What this means

SDD is the best structured approach we have for AI-assisted development today. Giving agents clear specs produces better code than working without any structure. BMAD, GSD, Spec Kit, Superpowers, and Kiro represent real engineering effort to bring order to a chaotic new space. Many developers use them, myself included. They work, up to a point.

The point where they stop working is change propagation. Requirements shift, design evolves during implementation, specs drift from code. Not because anyone messed up, but because that’s how building software works. The current mechanisms aren’t enough.

AI shifted the bottleneck from writing code to everything around it: specifying, reviewing, deciding, and propagating changes. The coding step got fast. The rest didn’t. And because AI agents follow specs without judgment, stale docs don’t just slow you down. They produce the wrong output. Every phase that reads an outdated spec makes the problem worse.

If SDD is more than a prototyping tool, and the frameworks position themselves that way with multi-milestone roadmaps and lifecycle tooling, then it needs propagation that matches the ambition. This isn’t something users can solve through discipline. It needs to be built into the framework: automated drift detection, incremental spec updates, and feedback from implementation back to specs.

The frameworks solved the easy problem: turning specs into code. The hard one is turning code back into specs. That’s still open.